Reposting something you wrote is a lot easier than coming up with original content. This article was originally posted as part of the 2008 PHP Advent Calendar

Last year I wrote some kind of feel-good, hippie crap for the PHP Advent Calendar. This year I got a haircut, took a shower, and am ready to tell you about something practical: working with JavaScript Object Notation (JSON) in PHP.

"JSON?!" you cry. "But that's for JavaScript fruitcakes!" And you'd be right. But JSON, while valid JavaScript code, is actually a very effective serialized data format for exchanging data between applications written in a variety of languages. And as of PHP 5.2, we have native support for JSON encoding and decoding.

But I Love XML!

Who doesn't? The thing is, for moving data around--not documents, but data--I think JSON is superior to XML. This is mainly because JSON tends to map better to the data models in most programming languages--arrays, objects, etc. JSON is serialized JavaScript, so it's easy peasy representing these kinds of things. Moving between JSON and your language's internal data models is usually just a single function call. Smarter people than me can debate the pros and cons of XML and JSON in various scenarios, but for a lot of what I do, JSON does the same thing and requires less work.

Get Your PHP Objects On

In PHP 5.2+, there are two functions that handle JSON: json_encode(), which takes a PHP data structure and returns a JSON string, and json_decode(), which takes a JSON string and converts it into a PHP data structure. Let's take a look at json_encode() and how it handles converting a PHP object into JSON:

<?php
// make a simple object
$obj->body           = 'another post';
$obj->id             = 21;
$obj->approved       = true;
$obj->favorite_count = 1;
$obj->status         = NULL;

// convert into JSON
$json_obj = json_encode($obj);
echo $json_obj;

This will output the following JSON string:

{"body":"another post","id":21,"approved":true,"favorite_count":1,"status":null}

Now, let's take that JSON and turn it back into PHP:

// convert back into PHP
$new_obj = json_decode($json_obj);
var_dump($new_obj);

And we'll have the following PHP object:

object(stdClass)#2 (5) {
  ["body"]=>
  string(12) "another post"
  ["id"]=>
  int(21)
  ["approved"]=>
  bool(true)
  ["favorite_count"]=>
  int(1)
  ["status"]=>
  NULL
}

Notice that the data types are retained in the process. JSON supports strings, numbers, objects, arrays (kinda), booleans and NULL. Things like methods, constants, and non-public properties are dropped in the encoding process, as shown in the example below:

<?php
class Foo {
  const     ERROR_CODE = '404';
  public    $public_ex = 'this is public';
  private   $private_ex = 'this is private!';
  protected $protected_ex = 'this should be protected';

  public function getErrorCode() {
    return self::ERROR_CODE;
  }
}

$foo = new Foo
$foo_json = json_encode($foo
echo $foo_json

This outputs the following JSON:

{"public_ex":"this is public"}

Also note that when you decode JSON into a PHP object, the object type is always stdClass. If we use $foo_json from above…

$foo_new = json_decode($foo_json);
var_dump($foo_new);

…we'll get back the following object:

object(stdClass)#4 (1) {
 ["public_ex"]=>
 string(14) "this is public"
}

Arrays, Indexed & Associative

Array support in JSON is limited to indexed arrays--those with sequential, numeric keys. Associative arrays are converted into an object with corresponding properties.

<?php
// here's an indexed array. JSON natively handles these
$arr = array('orange', 'yellow', 'green', 122);
$json_arr = json_encode($arr);
echo $json_arr."\n";

That gives us this JSON:

["orange","yellow","green",122]

And we can convert it back into PHP…

$new_arr = json_decode($json_arr);
var_dump($new_arr);

…without losing anything in the process.

array(4) {
  [0]=>
  string(6) "orange"
  [1]=>
  string(6) "yellow"
  [2]=>
  string(5) "green"
  [3]=>
  int(122)
}

With associative arrays, the array is converted to an object. Also note that all associative keys are converted into strings in the process:

// associative PHP arrays are converted into objects
$assoc = array('orange'=>'yellow', 'green'=>122, 9=>122);
$json_assoc = json_encode($assoc);

The encoded JSON will be {"orange":"yellow","green":122,"9":122}. Decoding that gives us this PHP object:

object(stdClass)#5 (3) {
  ["orange"]=>
  string(6) "yellow"
  ["green"]=>
  int(122)
  ["9"]=>
  int(122)
}

You can, however, convert the JSON object back into a PHP associative array by passing TRUE as the second param to json_decode() (thanks Richard Orelup).

Playing Well with Others

That's all fine and good, but it might help to actually do something useful with all this encodin' and decodin'. JSON is a really good choice for moving data between client-side JavaScript applications and server-side applications, because JSON is JavaScript code, and maps perfectly onto JavaScript's data structures.

So, let's contrive a simple application that passes a "counter" object back and forth between the client and server. The counter object stores information on how often the PHP server application and the JavaScript client application "touch" it. First, we'll make a PHP script to serve up some JSON code to our JavaScript client. It will look for an action parameter in $_GET, perform the requested action, and serve up some JSON in return.

<?php
if ($_GET['action'] === "getinit") {

  // make the PHP object and add a PHP touch
  $counter->php_touches    = 1;
  $counter->js_touches    = 0;
  send_as_json($counter);

} elseif ($_GET['action'] === "updatedata") {
  // decode JSON
  $counter = json_decode($_POST['counter']);

  // increment php touch counter
  $counter->php_touches++;

  // serve up as JSON
  send_as_json($counter);

} else {
  send_as_json(false);
}


function send_as_json($obj) {

  // convert object to JSON
  $json = json_encode($obj);

  // set appropriate headers
  header('Content-Type: application/json');

  // output JSON string as body
  echo $json;
}

The getinit action will create a $counter object, initialize it with a couple of variables to track "touches" by PHP and JSON, and serve up the object as JSON via the send_as_json() function. The updatedata action will take JSON from the $_POST array, decode it into the $counter object, increment the php_touches property, and serve up the modified object as JSON.

In the send_as_json() function, note the header() call that sets the Content-Type to application/json. Setting the content type correctly is good practice, and will sometimes avoid unexpected security issues.

On the client side, we'll make a short HTML page with some embedded JavaScript to interact with our PHP service.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  <title>JSON PHP Example</title>
  <!-- Load the Google JS libs hosting API -->
  <script src="http://www.google.com/jsapi"></script>
  <!-- Load the newest jquery major version 1 from Google -->
  <script type="text/javascript" charset="utf-8">
    google.load("jquery", "1");
  </script>
  <!-- load the JSON2.js parser -->
  <script src="JSON2.js"></script>

  <script type="text/javascript" charset="utf-8">
    var counter;

    function processData(data, textStatus) {
      counter = JSON.parse(data);
      counter.js_touches++;
      $('#js-count').val( parseInt(counter.js_touches));
      $('#php-count').val( parseInt(counter.php_touches));
    }

    // when the DOM is ready, do this stuff
    $(document).ready( function() {
      $.get('jsonphp.php?action=getinit', processData, 'text');
      $('#increment-button').click( function() {
        counter.js_touches = parseInt( $('#js-count').val() );
        counter.php_touches = parseInt( $('#php-count').val() );
        var json = JSON.stringify(counter);
        $.post('jsonphp.php?action=updatedata', { 'counter':json }, processData, 'text');
      });
    });
  </script>

  <style type="text/css" media="screen">
    body, input {
      font-family: Baskerville, Georgia, "Times New Roman", serif;
    }
    table {
      border:1px solid #CCC;
      padding:.2em;
      margin: .2em;
    }
    td.label {
      text-align:right;
      font-weight:bold;
    }
  </style>
</head>
<body>
  <table>
    <tr>
      <td class="label">JavaScript Touches:</td>
      <td><input type="text" id="js-count" value="0" /></td>
    </tr>
    <tr>
      <td class="label">PHP Touches:</td>
      <td><input type="text" id="php-count" value="0" /></td>
    </tr>
  </table>
  <form>
    <input type="button" name="increment" value="Increment!" id="increment-button" />
  </form>
</body>
</html>

Rendered in the browser, the page will look something like this:

Note that we're using the jQuery library (loaded from the Google JavaScript Libraries API) to handle DOM manipulation and Ajax calls. We're also using the JSON2.js parser, available at JSON.org, to safely parse and create JSON. The default method for decoding JSON into a JavaScript object or array is eval(), but that leaves us open to all sorts of code injection issues.

Jumping into our JavaScript code, the $().ready() is the most interesting portion. The ready() method called on $(document) takes the anonymous function passed into it, and executes the function as soon as the document is "ready"--that is, when the DOM is completed and can be safely messed with. So, when the DOM is ready, two things will happen:

• A GET request is made to jsonphp.php?action=getinit, and the results are passed as text to the processData() function

• An event listener is assigned to the click event for the button with the id of increment-button. This listener will fire a function that:

  1. Grabs the values for the touch counts out of the form fields

  2. Assigns them to the counter object

  3. Encodes the counter object as JSON

  4. POSTs counter to the server

So, each time we click the "Increment!" button, the object is sent from the JavaScript application to the PHP application as JSON. Each side will increment its own counter in the object, and the JavaScript application will display those values to us in the page. If we want, we can even change the values, and the JavaScript application will bind the new values to the object before sending it to the server.

What's It All Mean, Dave?

Metaphysically, I have no idea. But practically, JSON support in PHP means that our favorite server-side language is an even better glue language-- something it's been good at for a long time. Now, go forth and make the next mega-ajax-crowdsourced-mashup masterpiece.

Reposting something you wrote is a lot easier than coming up with original content. This article was originally posted as part of the 2008 PHP Advent Calendar

Last year I wrote some kind of feel-good, hippie crap for the PHP Advent Calendar. This year I got a haircut, took a shower, and am ready to tell you about something practical: working with JavaScript Object Notation (JSON) in PHP.

"JSON?!" you cry. "But that's for JavaScript fruitcakes!" And you'd be right. But JSON, while valid JavaScript code, is actually a very effective serialized data format for exchanging data between applications written in a variety of languages. And as of PHP 5.2, we have native support for JSON encoding and decoding.

But I Love XML!

Who doesn't? The thing is, for moving data around--not documents, but data--I think JSON is superior to XML. This is mainly because JSON tends to map better to the data models in most programming languages--arrays, objects, etc. JSON is serialized JavaScript, so it's easy peasy representing these kinds of things. Moving between JSON and your language's internal data models is usually just a single function call. Smarter people than me can debate the pros and cons of XML and JSON in various scenarios, but for a lot of what I do, JSON does the same thing and requires less work.

Get Your PHP Objects On

In PHP 5.2+, there are two functions that handle JSON: json_encode(), which takes a PHP data structure and returns a JSON string, and json_decode(), which takes a JSON string and converts it into a PHP data structure. Let's take a look at json_encode() and how it handles converting a PHP object into JSON:

<?php
// make a simple object
$obj->body           = 'another post';
$obj->id             = 21;
$obj->approved       = true;
$obj->favorite_count = 1;
$obj->status         = NULL;

// convert into JSON
$json_obj = json_encode($obj);
echo $json_obj;

This will output the following JSON string:

{"body":"another post","id":21,"approved":true,"favorite_count":1,"status":null}

Now, let's take that JSON and turn it back into PHP:

// convert back into PHP
$new_obj = json_decode($json_obj);
var_dump($new_obj);

And we'll have the following PHP object:

object(stdClass)#2 (5) {
  ["body"]=>
  string(12) "another post"
  ["id"]=>
  int(21)
  ["approved"]=>
  bool(true)
  ["favorite_count"]=>
  int(1)
  ["status"]=>
  NULL
}

Notice that the data types are retained in the process. JSON supports strings, numbers, objects, arrays (kinda), booleans and NULL. Things like methods, constants, and non-public properties are dropped in the encoding process, as shown in the example below:

<?php
class Foo {
  const     ERROR_CODE = '404';
  public    $public_ex = 'this is public';
  private   $private_ex = 'this is private!';
  protected $protected_ex = 'this should be protected';

  public function getErrorCode() {
    return self::ERROR_CODE;
  }
}

$foo = new Foo
$foo_json = json_encode($foo
echo $foo_json

This outputs the following JSON:

{"public_ex":"this is public"}

Also note that when you decode JSON into a PHP object, the object type is always stdClass. If we use $foo_json from above…

$foo_new = json_decode($foo_json);
var_dump($foo_new);

…we'll get back the following object:

object(stdClass)#4 (1) {
 ["public_ex"]=>
 string(14) "this is public"
}

Arrays, Indexed & Associative

Array support in JSON is limited to indexed arrays--those with sequential, numeric keys. Associative arrays are converted into an object with corresponding properties.

<?php
// here's an indexed array. JSON natively handles these
$arr = array('orange', 'yellow', 'green', 122);
$json_arr = json_encode($arr);
echo $json_arr."\n";

That gives us this JSON:

["orange","yellow","green",122]

And we can convert it back into PHP…

$new_arr = json_decode($json_arr);
var_dump($new_arr);

…without losing anything in the process.

array(4) {
  [0]=>
  string(6) "orange"
  [1]=>
  string(6) "yellow"
  [2]=>
  string(5) "green"
  [3]=>
  int(122)
}

With associative arrays, the array is converted to an object. Also note that all associative keys are converted into strings in the process:

// associative PHP arrays are converted into objects
$assoc = array('orange'=>'yellow', 'green'=>122, 9=>122);
$json_assoc = json_encode($assoc);

The encoded JSON will be {"orange":"yellow","green":122,"9":122}. Decoding that gives us this PHP object:

object(stdClass)#5 (3) {
  ["orange"]=>
  string(6) "yellow"
  ["green"]=>
  int(122)
  ["9"]=>
  int(122)
}

Playing Well with Others

That's all fine and good, but it might help to actually do something useful with all this encodin' and decodin'. JSON is a really good choice for moving data between client-side JavaScript applications and server-side applications, because JSON is JavaScript code, and maps perfectly onto JavaScript's data structures.

So, let's contrive a simple application that passes a "counter" object back and forth between the client and server. The counter object stores information on how often the PHP server application and the JavaScript client application "touch" it. First, we'll make a PHP script to serve up some JSON code to our JavaScript client. It will look for an action parameter in $_GET, perform the requested action, and serve up some JSON in return.

<?php
if ($_GET['action'] === "getinit") {

  // make the PHP object and add a PHP touch
  $counter->php_touches    = 1;
  $counter->js_touches    = 0;
  send_as_json($counter);

} elseif ($_GET['action'] === "updatedata") {
  // decode JSON
  $counter = json_decode($_POST['counter']);

  // increment php touch counter
  $counter->php_touches++;

  // serve up as JSON
  send_as_json($counter);

} else {
  send_as_json(false);
}


function send_as_json($obj) {

  // convert object to JSON
  $json = json_encode($obj);

  // set appropriate headers
  header('Content-Type: application/json');

  // output JSON string as body
  echo $json;
}

The getinit action will create a $counter object, initialize it with a couple of variables to track "touches" by PHP and JSON, and serve up the object as JSON via the send_as_json() function. The updatedata action will take JSON from the $_POST array, decode it into the $counter object, increment the php_touches property, and serve up the modified object as JSON.

In the send_as_json() function, note the header() call that sets the Content-Type to application/json. Setting the content type correctly is good practice, and will sometimes avoid unexpected security issues.

On the client side, we'll make a short HTML page with some embedded JavaScript to interact with our PHP service.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  <title>JSON PHP Example</title>
  <!-- Load the Google JS libs hosting API -->
  <script src="http://www.google.com/jsapi"></script>
  <!-- Load the newest jquery major version 1 from Google -->
  <script type="text/javascript" charset="utf-8">
    google.load("jquery", "1");
  </script>
  <!-- load the JSON2.js parser -->
  <script src="JSON2.js"></script>

  <script type="text/javascript" charset="utf-8">
    var counter;

    function processData(data, textStatus) {
      counter = JSON.parse(data);
      counter.js_touches++;
      $('#js-count').val( parseInt(counter.js_touches));
      $('#php-count').val( parseInt(counter.php_touches));
    }

    // when the DOM is ready, do this stuff
    $(document).ready( function() {
      $.get('jsonphp.php?action=getinit', processData, 'text');
      $('#increment-button').click( function() {
        counter.js_touches = parseInt( $('#js-count').val() );
        counter.php_touches = parseInt( $('#php-count').val() );
        var json = JSON.stringify(counter);
        $.post('jsonphp.php?action=updatedata', { 'counter':json }, processData, 'text');
      });
    });
  </script>

  <style type="text/css" media="screen">
    body, input {
      font-family: Baskerville, Georgia, "Times New Roman", serif;
    }
    table {
      border:1px solid #CCC;
      padding:.2em;
      margin: .2em;
    }
    td.label {
      text-align:right;
      font-weight:bold;
    }
  </style>
</head>
<body>
  <table>
    <tr>
      <td class="label">JavaScript Touches:</td>
      <td><input type="text" id="js-count" value="0" /></td>
    </tr>
    <tr>
      <td class="label">PHP Touches:</td>
      <td><input type="text" id="php-count" value="0" /></td>
    </tr>
  </table>
  <form>
    <input type="button" name="increment" value="Increment!" id="increment-button" />
  </form>
</body>
</html>

Rendered in the browser, the page will look something like this:

Note that we're using the jQuery library (loaded from the Google JavaScript Libraries API) to handle DOM manipulation and Ajax calls. We're also using the JSON2.js parser, available at JSON.org, to safely parse and create JSON. The default method for decoding JSON into a JavaScript object or array is eval(), but that leaves us open to all sorts of code injection issues.

Jumping into our JavaScript code, the $().ready() is the most interesting portion. The ready() method called on $(document) takes the anonymous function passed into it, and executes the function as soon as the document is "ready"--that is, when the DOM is completed and can be safely messed with. So, when the DOM is ready, two things will happen:

• A GET request is made to jsonphp.php?action=getinit, and the results are passed as text to the processData() function

• An event listener is assigned to the click event for the button with the id of increment-button. This listener will fire a function that:

  1. Grabs the values for the touch counts out of the form fields

  2. Assigns them to the counter object

  3. Encodes the counter object as JSON

  4. POSTs counter to the server

So, each time we click the "Increment!" button, the object is sent from the JavaScript application to the PHP application as JSON. Each side will increment its own counter in the object, and the JavaScript application will display those values to us in the page. If we want, we can even change the values, and the JavaScript application will bind the new values to the object before sending it to the server.

What's It All Mean, Dave?

Metaphysically, I have no idea. But practically, JSON support in PHP means that our favorite server-side language is an even better glue language-- something it's been good at for a long time. Now, go forth and make the next mega-ajax-crowdsourced-mashup masterpiece.

The coming weeks are gonna be a little hectic for me, as I fly to Atlanta on the 12th to attend php|works / PyWorks 2008. I'll be doing the following talks:

• Building Desktop RIAs with PHP, HTML and Javascript in AIR
• The CodeIgniter Framework

I'm pretty excited about php|works / PyWorks 2008, especially because we can interact with the Python community and learn more about each other's tech. Cross-pollination is a Good Thing.

I'm flying back to IND on the 15th, but then I'm leaving again on the 16th for San Francisco and the Adobe MAX 2008 conference. I'm giving the following talk:

• Developing Rich Applications with jQuery and Adobe AIR

Originally this talk was going to be given by John Resig, creator of the jQuery library, but he ran into some time constraints and thoughtfully suggested me. Of course, the description still mentions his name, which likely means I'll be tarred and feathered by the audience. This also looks like it may be the largest audience I've ever given a talk before: there are currently about 70 folks listed as attending, with ~300 capacity. So if I wet myself on stage, please forgive me.