json_encode
Returns a string containing the JSON representation of the supplied value . If the parameter is an array or object , it will be serialized recursively.
If a value to be serialized is an object, then by default only publicly visible properties will be included. Alternatively, a class may implement JsonSerializable to control how its values are serialized to JSON .
The encoding is affected by the supplied flags and additionally the encoding of float values depends on the value of serialize_precision.
Parameters
The value being encoded. Can be any type except a resource.
All string data must be UTF-8 encoded.
Note:
PHP implements a superset of JSON as specified in the original » RFC 7159.
Bitmask consisting of JSON_FORCE_OBJECT , JSON_HEX_QUOT , JSON_HEX_TAG , JSON_HEX_AMP , JSON_HEX_APOS , JSON_INVALID_UTF8_IGNORE , JSON_INVALID_UTF8_SUBSTITUTE , JSON_NUMERIC_CHECK , JSON_PARTIAL_OUTPUT_ON_ERROR , JSON_PRESERVE_ZERO_FRACTION , JSON_PRETTY_PRINT , JSON_UNESCAPED_LINE_TERMINATORS , JSON_UNESCAPED_SLASHES , JSON_UNESCAPED_UNICODE , JSON_THROW_ON_ERROR . The behaviour of these constants is described on the JSON constants page.
Set the maximum depth. Must be greater than zero.
Return Values
Returns a JSON encoded string on success or false on failure.
Changelog
| Version | Description |
|---|---|
| 7.3.0 | JSON_THROW_ON_ERROR flags was added. |
| 7.2.0 | JSON_INVALID_UTF8_IGNORE , and JSON_INVALID_UTF8_SUBSTITUTE flags were added. |
| 7.1.0 | JSON_UNESCAPED_LINE_TERMINATORS flags was added. |
| 7.1.0 | serialize_precision is used instead of precision when encoding float values. |
Examples
Example #1 A json_encode() example
$arr = array( ‘a’ => 1 , ‘b’ => 2 , ‘c’ => 3 , ‘d’ => 4 , ‘e’ => 5 );
The above example will output:
Example #2 A json_encode() example showing some flags in use
echo «Normal: » , json_encode ( $a ), «\n» ;
echo «Tags: » , json_encode ( $a , JSON_HEX_TAG ), «\n» ;
echo «Apos: » , json_encode ( $a , JSON_HEX_APOS ), «\n» ;
echo «Quot: » , json_encode ( $a , JSON_HEX_QUOT ), «\n» ;
echo «Amp: » , json_encode ( $a , JSON_HEX_AMP ), «\n» ;
echo «Unicode: » , json_encode ( $a , JSON_UNESCAPED_UNICODE ), «\n» ;
echo «All: » , json_encode ( $a , JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP | JSON_UNESCAPED_UNICODE ), «\n\n» ;
echo «Empty array output as array: » , json_encode ( $b ), «\n» ;
echo «Empty array output as object: » , json_encode ( $b , JSON_FORCE_OBJECT ), «\n\n» ;
echo «Non-associative array output as array: » , json_encode ( $c ), «\n» ;
echo «Non-associative array output as object: » , json_encode ( $c , JSON_FORCE_OBJECT ), «\n\n» ;
$d = array( ‘foo’ => ‘bar’ , ‘baz’ => ‘long’ );
echo «Associative array always output as object: » , json_encode ( $d ), «\n» ;
echo «Associative array always output as object: » , json_encode ( $d , JSON_FORCE_OBJECT ), «\n\n» ;
?>
The above example will output:
Normal: [«»,»‘bar'»,»\»baz\»»,»&blong&»,»\u00e9″] Tags: [«\u003Cfoo\u003E»,»‘bar'»,»\»baz\»»,»&blong&»,»\u00e9″] Apos: [«»,»\u0027bar\u0027″,»\»baz\»»,»&blong&»,»\u00e9″] Quot: [«»,»‘bar'»,»\u0022baz\u0022″,»&blong&»,»\u00e9″] Amp: [«»,»‘bar'»,»\»baz\»»,»\u0026blong\u0026″,»\u00e9″] Unicode: [«»,»‘bar'»,»\»baz\»»,»&blong&»,»é»] All: [«\u003Cfoo\u003E»,»\u0027bar\u0027″,»\u0022baz\u0022″,»\u0026blong\u0026″,»é»] Empty array output as array: [] Empty array output as object: <> Non-associative array output as array: [[1,2,3]] Non-associative array output as object: > Associative array always output as object: Associative array always output as object:
Example #3 JSON_NUMERIC_CHECK option example
echo «Strings representing numbers automatically turned into numbers» . PHP_EOL ;
$numbers = array( ‘+123123’ , ‘-123123’ , ‘1.2e3’ , ‘0.00001’ );
var_dump (
$numbers ,
json_encode ( $numbers , JSON_NUMERIC_CHECK )
);
echo «Strings containing improperly formatted numbers» . PHP_EOL ;
$strings = array( ‘+a33123456789’ , ‘a123’ );
var_dump (
$strings ,
json_encode ( $strings , JSON_NUMERIC_CHECK )
);
?>
The above example will output something similar to:
Strings representing numbers automatically turned into numbers array(4) < [0]=>string(7) "+123123" [1]=> string(7) "-123123" [2]=> string(5) "1.2e3" [3]=> string(7) "0.00001" > string(28) "[123123,-123123,1200,1.0e-5]" Strings containing improperly formatted numbers array(2) < [0]=>string(13) "+a33123456789" [1]=> string(4) "a123" > string(24) "["+a33123456789","a123"]"
Example #4 Sequential versus non-sequential array example
echo «Sequential array» . PHP_EOL ;
$sequential = array( «foo» , «bar» , «baz» , «blong» );
var_dump (
$sequential ,
json_encode ( $sequential )
);
echo PHP_EOL . «Non-sequential array» . PHP_EOL ;
$nonsequential = array( 1 => «foo» , 2 => «bar» , 3 => «baz» , 4 => «blong» );
var_dump (
$nonsequential ,
json_encode ( $nonsequential )
);
echo PHP_EOL . «Sequential array with one key unset» . PHP_EOL ;
unset( $sequential [ 1 ]);
var_dump (
$sequential ,
json_encode ( $sequential )
);
?>
The above example will output:
Sequential array array(4) < [0]=>string(3) "foo" [1]=> string(3) "bar" [2]=> string(3) "baz" [3]=> string(5) "blong" > string(27) "["foo","bar","baz","blong"]" Non-sequential array array(4) < [1]=>string(3) "foo" [2]=> string(3) "bar" [3]=> string(3) "baz" [4]=> string(5) "blong" > string(43) "" Sequential array with one key unset array(3) < [0]=>string(3) "foo" [2]=> string(3) "baz" [3]=> string(5) "blong" > string(33) ""
Example #5 JSON_PRESERVE_ZERO_FRACTION option example
The above example will output:
Предопределённые константы
Перечисленные ниже константы определены данным модулем и могут быть доступны только в том случае, если PHP был собран с поддержкой этого модуля или же в том случае, если данный модуль был динамически загружен во время выполнения.
Следующие константы указывают на тип ошибки, возвращённой функцией json_last_error() или хранящейся, как code в JsonException .
JSON_ERROR_NONE ( int ) Не произошло никаких ошибок. JSON_ERROR_DEPTH ( int ) Была превышена максимальная глубина стека. JSON_ERROR_STATE_MISMATCH ( int ) Неверный или повреждённый JSON. JSON_ERROR_CTRL_CHAR ( int ) Ошибка управляющих символов, вероятно, из-за неверного кодирования. JSON_ERROR_SYNTAX ( int ) Синтаксическая ошибка. JSON_ERROR_UTF8 ( int ) Повреждённые символы UTF-8, вероятно, из-за неверного кодирования. JSON_ERROR_RECURSION ( int ) Объект или массив, переданный в функцию json_encode() включает рекурсивные ссылки и не может быть закодирован. Если была передана опция JSON_PARTIAL_OUTPUT_ON_ERROR , то на месте рекурсивных ссылок будет выведен null . JSON_ERROR_INF_OR_NAN ( int ) Значение, переданное в функцию json_encode() , включает либо NAN , либо INF . Если была указана константа JSON_PARTIAL_OUTPUT_ON_ERROR , то вместо указанных особых значений будет выведен 0 . JSON_ERROR_UNSUPPORTED_TYPE ( int ) В функцию json_encode() было передано значение неподдерживаемого типа, например, resource. Если была указана константа JSON_PARTIAL_OUTPUT_ON_ERROR , то вместо неподдерживаемого значения будет выводиться null . JSON_ERROR_INVALID_PROPERTY_NAME ( int ) В строке переданной в json_decode() был ключ, начинающийся с символа \u0000. JSON_ERROR_UTF16 ( int ) Один непарный суррогат UTF-16 в экранированной последовательности Unicode в строке JSON, переданной в json_decode() .
Можно комбинировать следующие константы для передачи в json_decode() .
JSON_BIGINT_AS_STRING ( int ) Декодирует большие целые числа в качестве исходного значения строки. JSON_OBJECT_AS_ARRAY ( int ) Преобразует объекты JSON в массив PHP. Эта опция может быть задана автоматически, если вызвать json_decode() указав вторым параметром true .
Следующие константы можно комбинировать для использования в json_encode() .
JSON_HEX_TAG ( int ) Все < и >кодируются в \u003C и \u003E. JSON_HEX_AMP ( int ) Все & кодируются в \u0026. JSON_HEX_APOS ( int ) Все символы ‘ кодируются в \u0027. JSON_HEX_QUOT ( int ) Все символы » кодируются в \u0022. JSON_FORCE_OBJECT ( int ) Выдавать объект вместо массива при использовании неассоциативного массива. Это полезно, когда принимающая программа или код ожидают объект, а массив пуст. JSON_NUMERIC_CHECK ( int ) Кодирование строк, содержащих числа, как числа. JSON_PRETTY_PRINT ( int ) Использовать пробельные символы в возвращаемых данных для их форматирования. JSON_UNESCAPED_SLASHES ( int ) Не экранировать / . JSON_UNESCAPED_UNICODE ( int ) Не кодировать многобайтовые символы Unicode (по умолчанию они кодируются как \uXXXX). JSON_PARTIAL_OUTPUT_ON_ERROR ( int ) Позволяет избежать возникновения ошибок при использовании функции json_encode. Осуществляет подстановку значений по умолчанию вместо некодируемых. JSON_PRESERVE_ZERO_FRACTION ( int ) Гарантирует, что значение типа float будет преобразовано именно в значение типа float в случае, если дробная часть равна 0. JSON_UNESCAPED_LINE_TERMINATORS ( int ) Символы конца строки не будут экранироваться, если задана константа JSON_UNESCAPED_UNICODE . Поведение будет таким же, какое оно было до PHP 7.1 без этой константы. Доступно с PHP 7.1.0.
Следующие константы можно комбинировать для использования в json_decode() и json_encode() .
JSON_INVALID_UTF8_IGNORE ( int ) Игнорировать некорректные символы UTF-8. Доступно с PHP 7.2.0. JSON_INVALID_UTF8_SUBSTITUTE ( int ) Преобразовывать некорректные символы UTF-8 в \0xfffd (Символ Юникода ‘REPLACEMENT CHARACTER’) Доступно с PHP 7.2.0. JSON_THROW_ON_ERROR ( int ) Выбрасывается исключение JsonException в случае возникновения ошибок вместо установки глобального состояния ошибки, которое может быть получено с помощью функции json_last_error() и json_last_error_msg() . Константа JSON_PARTIAL_OUTPUT_ON_ERROR имеет приоритет над JSON_THROW_ON_ERROR . Доступно с PHP 7.3.0.