<document>
<header>
<product>resin</product>
<title>Quercus JSON</title>
<description>
<p>
<b>JSON</b> (JavaScript Object Notation) is a popular text data
exchange format with built-in support from Quercus since Resin 3.0.20.
One of the common uses of JSON in a PHP environment is for the server
to send JSON data to the user's browser.  Because the JSON language is
a subset of JavaScript, JSON-encoded text can be readily parsed on the
user's browser using JavaScript's <code>eval()</code> function.
</p>
</description>
   <type>tutorial</type>
   <tutorial-startpage>json.html</tutorial-startpage>
</header>

<body>

<localtoc/>

<s1 title="Files in this tutorial">
<deftable>
<tr>
  <th>File</th>
  <th>Description</th>
</tr>
<tr>
  <td><viewfile-link file="json.html"/></td>
  <td>The JSON example page</td>
</tr>
<tr>
  <td><viewfile-link file="json.php"/></td>
  <td>The JSON PHP page</td>
</tr>
</deftable>
</s1>

<s1 title="Using JSON in Quercus">

<p>
Quercus has built-in JSON support and JSON functionality is enabled the moment Quercus is started: no additional downloads are required.  Quercus sports two PHP functions for working with JSON: <i>json_encode</i> and <i>json_decode</i>.
</p>
<example>
  <b>json_encode(mixed php_object)</b>
        encodes any PHP array or object into JSON.
      
  <b>json_decode(string json_string [, bool is_assoc])</b>
        decodes JSON into a PHP array or object.
</example>
<p>
<i>json_decode</i> may return either a PHP array or object depending on the circumstances:
</p>
<ul>
<li>
If the text is that of a JSON <a href="http://www.json.org">array</a>,
decoding returns a non-associative PHP array.
</li><li>
If the text is that of a JSON object and the second argument to <i>json_decode</i> is not specified or is <i>false</i>, decoding returns a standard PHP object.
</li>
<li>
If the text is that of a JSON object and the second argument to <i>json_decode</i> is <i>true</i>, then decoding returns an associative PHP array.
</li>
</ul>
</s1>


<s1 title="Examples">
<s2 title="json_encode">
<p>
To encode an array into JSON:
</p>
<example>
 &lt;?php
   $array = array("a"=&gt;"Caucho", "b"=&gt;"Resin", "c"=&gt;"Quercus");
   $json = json_encode($array);
 ?&gt;
</example>
<p>
The value of $json would be: <i>'{"a":"Caucho", "b":"Resin", "c":"Quercus"}'</i>.
The JSON text may then be sent and used on the user's browser or to any client that can decode JSON.
</p>
</s2>

<s2 title="json_decode">
<p>
To decode JSON data into a standard PHP object in Quercus (using the above JSON text <i>$json</i> as an example):
</p>
<example>
 &lt;?php
  $object = json_decode($json);
 ?&gt;
</example>
<p>
<i>$object</i> would be a standard PHP object with three fields "a", "b", and "c" with values "Caucho", "Resin", and "Quercus" respectively.
</p>
</s2>

<s2 title="Simple Web Example">
<p>
Below is a simple example using JSON on the web.
</p>
<example>
 &lt;script type="text/javascript"&gt;
 
   &lt;?php
     $array = array("a"=&gt;"Caucho", "b"=&gt;"Resin", "c"=&gt;"Quercus");
     $json = json_encode($array);
     echo "var data = $json;";
   ?&gt;
   
   var decoded = eval("(" + data + ")");
   
   //Should output: "Quercus at work."
   document.write(decoded.c + " at work.");
 &lt;/script&gt;
</example>
</s2>

<s2 title="AJAX Example">

<p> JSON data is more commonly sent to
the browser via AJAX requests.  Suppose there are two files defined
below.  The PHP script in <i>json.php</i> encodes an array into JSON.
When the user's browser is directed to <i>json.html</i>, an AJAX
request receives JSON data from <i>json.php</i>.  Then the browser
calls <code>eval()</code> on the JSON data to recover a JavaScript object.
</p>

<s3 title="json.php:">
<example>
 &lt;?php
   $array = array("a"=&gt;"Caucho", "b"=&gt;"Resin", "c"=&gt;"Quercus");
   $json = json_encode($array);
   echo $json;
 ?&gt;
</example>
</s3>

<s3 title="json.html:">
<example>
 &lt;html&gt;
 &lt;head&gt;
 &lt;script type="text/javascript"&gt;
  
  var url = "data.php";
  function request() {  
    if (window.XMLHttpRequest)
     http_request = new XMLHttpRequest();
    else
     http_request = new ActiveXObject("Microsoft.XMLHTTP");
    http_request.onreadystatechange = function() {
        handle_json(http_request)
      };
    http_request.open("GET", url, true);
    http_request.send(null);
  }
  
  function handle_json(http_request) {
   if (http_request.readyState == 4) {
    document.firstForm.json.value = http_request.responseText;
    var decoded = eval("(" + http_request.responseText + ")");
    document.firstForm.decoded.value = decoded.a + "'s " +
        decoded.b + " with " + decoded.c + " at work.";
   }
  }
  
  function clearForm() {
   document.firstForm.json.value = "";
   document.firstForm.decoded.value = "";
  }
 &lt;/script&gt;
 &lt;/head&gt;
 &lt;body&gt;
  &lt;form name="firstForm"&gt;
   &lt;p&gt;JSON:&lt;br&gt;&lt;textarea name="json" cols="50"&gt;&lt;/textarea&gt;&lt;/p&gt;
   &lt;p&gt;Decoded:&lt;br&gt;&lt;textarea name="decoded" cols="50"&gt;&lt;/textarea&gt;&lt;/p&gt;
   &lt;input type="button" onclick="request()" value="AJAX Request"&gt;
   &lt;input type="button" onclick="clearForm()" value="Clear"&gt;
  &lt;/form&gt;
 &lt;/body&gt;
 &lt;/html&gt;
</example>
</s3>

</s2>
</s1>

<s1 title="External Links">
<ul>
  <li>
  <a href="http://www.json.org">Official JSON Homepage</a>
  </li>
  <li>
  <a href="http://en.wikipedia.org/wiki/JSON">JSON Wikipedia entry</a>
  </li>
  <li>
  <a href="http://wiki.caucho.com/Quercus:_JSON">Caucho's JSON Wiki entry</a>
  </li>
  <li>
  <a href="http://www.aurore.net/projects/php-json">C Implementation from which
  Quercus' JSON syntax is based off of
  </a>
  </li>
</ul>
</s1>

</body>
</document>
