json_encode

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL json >= 1.2.0)

json_encode — Возвращает JSON-представление данных

Описание

json_encode(mixed $value, int $flags = 0, int $depth = 512): string|false

Возвращает строку, содержащую JSON-представление для указанного value. Если параметр является массивом (array) или объектом (object), он будет рекурсивно сериализован.

Если сериализуемое значение является объектом, то по умолчанию будут включены только публично видимые свойства. В качестве альтернативы класс может реализовать интерфейс JsonSerializable для управления тем, как его значения сериализуются в JSON.

На кодирование влияет параметр flags и, кроме того, кодирование значений типа float зависит от значения serialize_precision.

Список параметров

value

value - значение, которое будет закодировано. Может быть любого типа, кроме resource.

Функция работает только с кодировкой UTF-8.

Замечание:
PHP реализует надмножество JSON, который описан в первоначальном » RFC 7159.

flags

Битовая маска, составляемая из значений 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. Смысл этих констант объясняется на странице JSON-констант.

depth

Устанавливает максимальную глубину. Должен быть больше нуля.

Возвращаемые значения

Возвращает строку (string), закодированную JSON или false в случае возникновения ошибки.

Список изменений

Версия	Описание
7.3.0	Добавлена константа `JSON_THROW_ON_ERROR` для параметра `flags`.
7.2.0	Добавлены константы `JSON_INVALID_UTF8_IGNORE` и `JSON_INVALID_UTF8_SUBSTITUTE` для параметра `flags`.
7.1.0	Добавлена константа `JSON_UNESCAPED_LINE_TERMINATORS` для параметра `flags`.
7.1.0	При кодировании чисел с плавающей точкой (float) используется serialize_precision вместо precision.

Примеры

Пример #1 Пример использования json_encode()

<?php
$arr = array('a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5);

echo json_encode($arr);
?>

Результат выполнения данного примера:

{"a":1,"b":2,"c":3,"d":4,"e":5}

Пример #2 Пример использования json_encode() с опциями

<?php
$a = array('<foo>',"'bar'",'"baz"','&blong&', "\xc3\xa9");

echo "Обычно: ",     json_encode($a), "\n";
echo "Теги: ",       json_encode($a, JSON_HEX_TAG), "\n";
echo "Апострофы: ",  json_encode($a, JSON_HEX_APOS), "\n";
echo "Кавычки: ",    json_encode($a, JSON_HEX_QUOT), "\n";
echo "Амперсанды: ", json_encode($a, JSON_HEX_AMP), "\n";
echo "Юникод: ",     json_encode($a, JSON_UNESCAPED_UNICODE), "\n";
echo "Все: ",        json_encode($a, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP | JSON_UNESCAPED_UNICODE), "\n\n";

$b = array();

echo "Отображение пустого массива как массива: ", json_encode($b), "\n";
echo "Отображение неассоциативного массива как объекта: ", json_encode($b, JSON_FORCE_OBJECT), "\n\n";

$c = array(array(1,2,3));

echo "Отображение неассоциативного массива как массива: ", json_encode($c), "\n";
echo "Отображение неассоциативного массива как объекта: ", json_encode($c, JSON_FORCE_OBJECT), "\n\n";

$d = array('foo' => 'bar', 'baz' => 'long');

echo "Ассоциативный массив всегда отображается как объект: ", json_encode($d), "\n";
echo "Ассоциативный массив всегда отображается как объект: ", json_encode($d, JSON_FORCE_OBJECT), "\n\n";
?>

Результат выполнения данного примера:

Обычно: ["<foo>","'bar'","\"baz\"","&blong&","\u00e9"]
Теги: ["\u003Cfoo\u003E","'bar'","\"baz\"","&blong&","\u00e9"]
Апострофы: ["<foo>","\u0027bar\u0027","\"baz\"","&blong&","\u00e9"]
Кавычки: ["<foo>","'bar'","\u0022baz\u0022","&blong&","\u00e9"]
Амперсанды: ["<foo>","'bar'","\"baz\"","\u0026blong\u0026","\u00e9"]
Юникод: ["<foo>","'bar'","\"baz\"","&blong&","é"]
Все: ["\u003Cfoo\u003E","\u0027bar\u0027","\u0022baz\u0022","\u0026blong\u0026","é"]

Отображение пустого массива как массива: []
Отображение неассоциативного массива как объекта: {}

Отображение неассоциативного массива как массива: [[1,2,3]]
Отображение неассоциативного массива как объекта: {"0":{"0":1,"1":2,"2":3}}

Ассоциативный массив всегда отображается как объект: {"foo":"bar","baz":"long"}
Ассоциативный массив всегда отображается как объект: {"foo":"bar","baz":"long"}

Пример #3 Пример использования опции JSON_NUMERIC_CHECK

<?php
echo "Строки, содержащие числа преобразуются в числа".PHP_EOL;
$numbers = array('+123123', '-123123', '1.2e3', '0.00001');
var_dump(
 $numbers,
 json_encode($numbers, JSON_NUMERIC_CHECK)
);
echo "Строки, содержащие некорректно заданные числа".PHP_EOL;
$strings = array('+a33123456789', 'a123');
var_dump(
 $strings,
 json_encode($strings, JSON_NUMERIC_CHECK)
);
?>

Результатом выполнения данного примера будет что-то подобное:

Строки, содержащие числа преобразуются в числа
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]"
Строки, содержащие некорректно заданные числа
array(2) {
  [0]=>
  string(13) "+a33123456789"
  [1]=>
  string(4) "a123"
}
string(24) "["+a33123456789","a123"]"

Пример #4 Пример с последовательными индексами, начинающимися с нуля, и непоследовательными индексами массивов

<?php
echo "Последовательный массив".PHP_EOL;
$sequential = array("foo", "bar", "baz", "blong");
var_dump(
 $sequential,
 json_encode($sequential)
);

echo PHP_EOL."Непоследовательный массив".PHP_EOL;
$nonsequential = array(1=>"foo", 2=>"bar", 3=>"baz", 4=>"blong");
var_dump(
 $nonsequential,
 json_encode($nonsequential)
);

echo PHP_EOL."Последовательный массив с одним удалённым индексом".PHP_EOL;
unset($sequential[1]);
var_dump(
 $sequential,
 json_encode($sequential)
);
?>

Результат выполнения данного примера:

Последовательный массив
array(4) {
  [0]=>
  string(3) "foo"
  [1]=>
  string(3) "bar"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(27) "["foo","bar","baz","blong"]"

Непоследовательный массив
array(4) {
  [1]=>
  string(3) "foo"
  [2]=>
  string(3) "bar"
  [3]=>
  string(3) "baz"
  [4]=>
  string(5) "blong"
}
string(43) "{"1":"foo","2":"bar","3":"baz","4":"blong"}"

Последовательный массив с одним удалённым индексом
array(3) {
  [0]=>
  string(3) "foo"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(33) "{"0":"foo","2":"baz","3":"blong"}"

Пример #5 Пример использования опции JSON_PRESERVE_ZERO_FRACTION

<?php
var_dump(json_encode(12.0, JSON_PRESERVE_ZERO_FRACTION));
var_dump(json_encode(12.0));
?>

Результат выполнения данного примера:

string(4) "12.0"
string(2) "12"

Примечания

Замечание:
в случае возникновения ошибки кодирования можно использовать json_last_error() для определения точной ошибки.

Замечание:
При кодировании массива в случае, если его индексы не являются последовательными числами от нуля, то все индексы кодируются в строковые ключи для каждой пары индекс-значение.

Замечание:
Как и эталонный кодировщик JSON, json_encode() будет создавать JSON в виде простого значения (то есть не объект и не массив), если ему переданы типы string, int, float или bool в качестве входящего значения value. Большинство декодеров воспринимают эти значения как правильный JSON, но некоторые нет, потому что спецификация неоднозначна на этот счёт.

Всегда проверяйте, что ваш декодер JSON может правильно обрабатывать данные, которые вы создаёте с помощью json_encode().

Смотрите также

JsonSerializable
json_decode() - Декодирует строку JSON
json_last_error() - Возвращает последнюю ошибку
serialize() - Генерирует пригодное для хранения представление переменной