Similar to XML, JavaScript Object Notation (JSON) was designed as a standardized data-interchange format. However, unlike XML, JSON is extremely lightweight and human-readable. While it takes many syntax cues from JavaScript, JSON is designed to be language-independent.
JSON is built on two structures: collections of name/value pairs called objects (equivalent to PHP’s associative arrays) and ordered lists of values called arrays (equivalent to PHP’s indexed arrays). Each value can be one of a number of types: an object, an array, a string, a number, the Boolean values TRUE
or FALSE
, or NULL
(indicating a lack of a value).
The json extension, included by default in PHP installations, natively supports converting data to JSON format from PHP variables and vice versa.
To get a JSON representation of a PHP variable, use json_encode()
:
$data = array(1, 2, "three"); $jsonData = json_encode($data); echo $jsonData; [1, 2, "three"]
Similarly, if you have a string containing JSON data, you can turn it into a PHP variable using json_decode()
:
$jsonData = "[1, 2, [3, 4], "five"]"; $data = json_decode($jsonData); print_r($data); Array( [0] => 1 [1] => 2 [2] => Array( [0] => 3 [1] => 4 ) [3] => five)
If the string is invalid JSON, or if the string is not encoded in UTF-8 format, a single NULL
value is returned instead.
The value types in JSON are converted to PHP equivalents as follows:
object
array
string
number
NULL
, unless json_decode()
is called with the JSON_BIGINT_AS_STRING
(in which case, a string is returned).boolean
true
value is converted to TRUE
; the Boolean false
value is converted to FALSE
.null
null
value, and any value that cannot be decoded, is converted to NULL
.Despite the similar names, there is no direct translation between PHP objects and JSON objects—what JSON calls an “object” is really an associative array. To convert JSON data into an instance of a PHP object class, you must write code to do so based on the format returned by the API.
However, the JsonSerializable
interface allows you to convert objects into JSON data however you like. If an object class does not implement the interface, json_encode()
simply creates a JSON object containing keys and values corresponding to the object’s data members.
Otherwise, json_encode()
calls the jsonSerialize()
method on the class and uses that to serialize the object’s data.
Example 13-1 adds the JsonSerializable
interface to the Book
and Author
classes.
Creating a PHP object from JSON data requires you to write code to perform the translation.
Example 13-2 shows a class implementing Factory-style transformation of JSON data into Book
and Author
instances into PHP objects.
The JSON parser functions have several options you can set to control the conversion process.
For json_decode()
, the most common options include:
JSON_BIGINT_AS_STRING
JSON_OBJECT_AS_ARRAY
For json_encode()
, the most common options include:
JSON_FORCE_OBJECT
JSON_NUMERIC_CHECK
JSON_PRETTY_PRINT
Finally, the following options can be used for both json_encode()
and json_decode()
:
JSON_INVALID_UTF8_IGNORE
JSON_INVALID_UTF8_SUBSTITUTE
is also set, replaces them; otherwise, drops them in the resulting string.JSON_INVALID_UTF8_SUBSTITUTE