<document>
<header>
<product>resin</product>
<title>Quercus JSON</title>
<description>
<p>
<b>JSON</b> (<b>J</b>ava<b>S</b>cript <b>O</b>bject <b>N</b>otation) 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 <i>eval()</i> function.
</p>
</description>
</header>

<body>
<summary localtoc="3" />
<section 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( object/array )</b>
        encodes any PHP array or object into JSON.
      
  <b>json_decode( string, [, bool] )</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 array<sup><a href="http://www.json.org">[1]</a></sup>,  decoding returns a non-associative PHP array.
<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>
</section>


<section title="Examples">
<section title="json_encode">
<p>
To encode an array into JSON:
</p>
<example>
 &lt;?php
   $array = array("a"=>"Caucho", "b"=>"Resin", "c"=>"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>
</section>

<section 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>
</section>

<section 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"=>"Caucho", "b"=>"Resin", "c"=>"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>
</section>

<section 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>data.php</i> encodes an array into JSON.  When the user's browser is directed to <i>index.html</i>, an AJAX request receives JSON data from <i>data.php</i>.  Then the browser calls <i>eval()</i> on the JSON data to recover a JavaScript object.
</p>

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

<section title="index.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;
    <b>var decoded = eval("(" + http_request.responseText + ")");</b>
    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">
   &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>
</section>

<section title="AJAX example in action">
Click <a href="index.html">here</a> to see this example in action.
</section>

</section>
</section>

<section 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>
</section>

</body>
</document>

