When Crockford first proposed JSON, he was the only one creating tools for encoding and decoding. As the popularity of JSON grew, others started to step up and create client- and server-side libraries to facilitate its use. Although it is beyond the scope of this book to discuss every one of these tools, it is useful to take a look at one and then develop a solution using it.
JSON-PHP is a PHP library for encoding and decoding JSON information. This utility, written by Michal Migurski, is available for free at http://mike.teczno.com/json.html. To use this library, simply include the JSON.php file and create an instance of the Services_JSON object:
<?php require_once("JSON.php"); $oJSON = new Services_JSON(); ?>
The first line includes the JSON.php file that contains the Services_JSON object definition. The second line simply instantiates the object and stores it in the variable $oJSON. Now, you're ready to start encoding and decoding JSON in your PHP page.
To encode a PHP object into a JSON string, use the encode() method, which accepts a single argument: an object to encode, which can be an array or a full-fledged object. It doesn't matter how the object or array was created, by using a class definition or not; all objects can be encoded using this method. Consider the following class definition:
<?php class Person { var $age; var $hairColor; var $name; var $siblingNames; function Person($name, $age, $hairColor) { $this->name = $name; $this->age = $age; $this->hairColor = $hairColor; $this->siblingNames = array(); } } ?>
This PHP code defines a class called Person that stores some personal information. The class would be used as follows:
<?php $oPerson = new Person("Mike", 26, "brown"); $oPerson->siblingNames[0] = "Matt"; $oPerson->siblingNames[1] = "Tammy"; ?>
To encode the $oPerson object, simply pass it into the encode() method, like this:
<?php $sJSONText = $oJSON->encode($oPerson); ?>
This creates a JSON string of:
{"age":26,"hairColor":"brown","name":"Mike","siblingNames":["Matt","Tammy"]}
The $oPerson object is now ready to be transferred to JavaScript or any other language that can support JSON-encoded information.
The decode() method is used to perform the opposite function, taking a JSON string and parsing it into an object. Suppose that you have the JSON string displayed previously and want to create a PHP object from it. Just pass the string into the decode() method:
<?php $oPerson = $oJSON->decode($sJSONText); ?>
Now, the $oPerson variable can be used just like the one in the previous example, as if it were created using the Person class:
<?php print("<h3>Person Information</h3>"); print("<p>Name: ".$oPerson->name."<br />"); print("Age: ".$oPerson->age."<br />"); print("Hair Color: ".$oPerson->hairColor."<br />"); print("Sibling Names:</p><ul>"); for ($i=0; $i < count($oPerson->siblingNames); $i++) { print("<li>".$oPerson->siblingNames[$i]."</li>"); } print("</ul>"); ?>
This code prints out the information contained in the $oPerson object, proving that the object has been constructed appropriately. JSON-PHP is in several projects throughout this book because it is quite simply the easiest way to deal with JSON in a server-side language.
As of 2006, there are JSON libraries for use with every popular server-side language. Depending on your environment, you may find these resources useful:
C#/.NET: The Json.NET library is a free JSON parser/serializer that mimics the built-in XML functionality of .NET. Json.NET is available at www.newtonsoft.com/products/json.
ColdFusion: The CFJSON library, written by Jehiah Czebotar, is available at http://jehiah.com/projects/cfjson.
Java/JSP: The JSON in Java utilities, written by Douglas Crockford, are available at www.json.org/java/.
Perl: The JSON library, written by Makamaka Hannyaharamitu, is available at http://search.cpan.org/dist/JSON/.
PHP: In addition to JSON-PHP, there is also php-json, a C extension for PHP written by Omar Kilani and available at www.aurore.net/projects/php-json/. You must be comfortable with compiling PHP with extensions.
Python: The json-py library, written by Patrick D. Logan, is available at https://sourceforge.net/projects/json-py/.
Douglas Crockford also maintains a fairly comprehensive list of JSON utilities at www.json.org. It's a good idea to check there for other language needs.