PHP Advent 2008 Post: JSON is Everybody’s Friend

Security

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:

Screenshot

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.

  • till
    http://till.klampaeckel.de/blog
    12/24/2008 09:42:12 AM

    Enjoyed reading this. Thanks very much! :)

  • Chris Shiflett
    http://shiflett.org/
    12/24/2008 12:25:24 PM

    I would never have a superfluous slash in a URL like this:

    http://phpadvent.org/2008/

    My URLs are hand-crafted just for you, Ed. :-)

  • Chris Shiflett
    http://shiflett.org/
    12/24/2008 12:25:59 PM

    Oh cool, your blog no longer hates me.

  • Richard Orelup
    12/24/2008 01:18:08 PM

    Just reading through and had one correction with the associative arrays coming back as objects. json_decode has an optional parameter that if you send as true it will come back as an array instead of an object.

    $json_assoc = json_decode($assoc, true);

    Other then that great article that I know I will keep around to give to my students to help them understand json.

    Thanks, Richard

  • funkatron
    http://funkatron.com
    12/24/2008 07:52:17 PM

    Thanks Richard! I’ve updated the article accordingly. I’d be very interested to know if the article is useful to your students.

  • Mark McDonnell
    http://www.storm-media.co.uk/
    12/26/2008 07:36:27 PM

    Unfortunately the example code you provided doesn’t work.

    It’s fine for the initial load, but when you click on the ‘increment’ button the js_touch field gets set to NULL and the php_touch field stays as 1.

    I used Firebug to try and work out what was happening and I could see that although the data was being sent as {”php_touches”:1,”js_touches”:1} the PHP script was sending back only {”php_touches”:1} so it looks like the js_touch part of the posted JSON data isn’t being decoded properly.

    I would be interested to know how to fix this bug. Any help appreciated!

    Kind regards,

    M.

  • funkatron
    http://funkatron.com
    12/26/2008 11:12:20 PM

    I double-checked by copying and pasting the exact code listings here, and it works fine. I tested it with Firefox 3.0.5 and PHP 5.2.5, both on OS X.

  • Mark McDonnell
    http://www.storm-media.co.uk/
    12/27/2008 01:49:41 PM

    Hmmm, interesting.

    I also did a copy and paste, I’m using Windows XP Professional with PHP 5.2.8 and it doesn’t seem to work.

  • funkatron
    http://funkatron.com
    12/27/2008 03:13:54 PM

    I unfortunately don’t have a 5.2.8 install to test with. I’d be curious to know if this is a change in behavior between 5.2.5 and 5.2.8.