The json_extension_api.php
file has been
created with the goal of letting developers write applications taking
advantage of the functionality offered by the php JSON extension, and
allow them to deploy on php installations where that extension is not
/cannot be installed. Since the reimplementation is written in 100% php,
it can be deployed on virtually any php setup by simply copying three
php files. The API of the native library is reproduced feature for
feature and bug for bug, with the following exceptions:
when trying to json_encode()
a php
string value that contains characters outside of the UTF-8
encoding range, this implementation will return a json string
containing different characters from the ones intended (a.k.a.
garbage), while the native extension discards invalid characters
and any following. Please note that if you are trying to do this
your code is most probably wrong.
<?php var_dump(json_encode("Günter, Elène"));
// this implenentation
string(19) ""Gnter, El\u8ba5ne""
// native extension
string(3) ""G""
when calling json_encode()
on a php
float value, the json representation generated by this
implementation will always contain a fractional part, whereas the
native extension does not. This feature allow us, when using this
implementation to both encode and decode, to distinguish between
int and float values and rebuild them with the correct php type,
despite the JSON protocol lacks two separate types.
<?php var_dump(json_encode(1.0);
// this implementation
string(3) "1.0"
// native extension
string(1) "1"
An interesting feature of this implementation, not offered by the native implementation, is that it allows to transparently encode/decode php strings to/from json using the ISO-8859-1 character set for the php representation, instead of UTF-8. ISO-8859-1 is the native character set of php, so this is the behaviour that is most likely to best fit the majority of usages.
Please note that if you include()
the
json_extension_api.php
file on a php installation
where the native JSON extension is loaded, the functions provided by
this implementation will be automatically renamed to
json_alt_encode
and
json_alt_decode
. This prevents function name
clashes and makes it easy to compare the output of the two
implementations.
Encode a php value into a JSON formatted string.
See the description in the php manual for more details.
Decode a a JSON formatted string into the corresponding php value(s). Returns NULL on error.
See the description in the php manual for more details.
The character set to which the JSON strings will be converted
by json_decode()
. Defaults to "UTF-8" for
compatibility with the php json extension, but can be set to
"ISO-8859-1" or "ASCII".
The behaviour of the php json extension was changed in between
versions. Up to version 1.2.0, calling
json_decode()
on strings representing
scalar json values (ie. strings, booleans, numbers and null) not
encapsulated within an array or struct would return false. From
version 1.2.1 onwards, decoding single scalar json values is
allowed. By setting the value of the global variable
$json_extension_api_120_behaviour
to true or
false, the behaviour of the emulation layer will be altered to
follow the different versions of the extension.