JSON-кодирование в PHP

JSON (JavaScript Object Notation) — это лёгкий текстовый формат обмена данными, который удобно читать людям и легко разбирать машинам. Это де-факто стандарт для передачи данных между сервером и браузером, для REST API и для конфигурационных файлов. В PHP функция json_encode() принимает значение PHP — скаляр, массив или объект — и возвращает его JSON-представление в виде строки.

На этой странице рассматриваются синтаксис, наиболее полезные $flags, соответствие типов PHP типам JSON и способы обнаружения ошибок кодирования. Для обратного преобразования (JSON-строка → значение PHP) смотрите json_decode().

Синтаксис

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

Функция возвращает JSON-строку в случае успеха или false при сбое (например, если входные данные содержат некорректный UTF-8).

Параметры

• $value — значение для кодирования. Может быть любого типа кроме resource. Все строковые данные должны быть корректным UTF-8.
• $flags (необязательный) — битовая маска, настраивающая вывод. Наиболее распространённые:
  • JSON_PRETTY_PRINT — добавляет пробелы и отступы, чтобы вывод был читаемым.
  • JSON_UNESCAPED_UNICODE — сохраняет многобайтовые символы (é, ñ, 日) как есть, вместо экранирования их в виде \uXXXX.
  • JSON_UNESCAPED_SLASHES — оставляет / без экранирования (по умолчанию PHP экранирует его как \/).
  • JSON_FORCE_OBJECT — кодирует последовательный массив как JSON-объект ({}) вместо массива ([]).
  • JSON_THROW_ON_ERROR — бросает исключение JsonException при сбое вместо возврата false (PHP 7.3+).
  • Флаги объединяются с помощью побитового оператора OR: JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE.
• $depth (необязательный) — максимальная глубина вложенности. Должна быть больше 0. Значение по умолчанию 512 достаточно для обычных данных.

Соответствие типов PHP типам JSON

Примеры

Кодирование массива

Ассоциативный массив PHP становится JSON-объектом; ключи становятся именами свойств.

Вывод:

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

Кодирование объекта

Публичные свойства объекта кодируются; свойства private и protected пропускаются.

Вывод:

{"name":"John Doe","age":35,"city":"New York"}

Красивый вывод и Unicode без экранирования

По умолчанию вывод компактный, в одну строку, а символы, выходящие за пределы ASCII, экранируются (например, é превращается в é). Два флага делают вывод удобочитаемым:

<?php

$data = [
    "name"  => "Café",
    "tags"  => ["php", "json"],
    "price" => 9.50,
];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

?>

Вывод:

{
    "name": "Café",
    "tags": [
        "php",
        "json"
    ],
    "price": 9.5
}

Обратите внимание: 9.50 выводится как 9.5 — хвостовые нули у дробных чисел отбрасываются. Используйте JSON_PRESERVE_ZERO_FRACTION, если нужно, чтобы 9.0 оставалось дробным числом, а не превращалось в 9.

Обработка ошибок

Если json_encode() возвращает false, что-то пошло не так — чаще всего это некорректный UTF-8 в строке. Проверьте json_last_error_msg() или передайте JSON_THROW_ON_ERROR, чтобы получить исключение.

<?php

$value = json_encode("\xB1\x31"); // invalid UTF-8 byte sequence

if ($value === false) {
    echo "Encoding failed: " . json_last_error_msg();
}

?>

Вывод:

Encoding failed: Malformed UTF-8 characters, possibly incorrectly encoded

Частые случаи использования

• Возврат данных из API. Установите заголовок и выведите закодированный массив:

  header('Content-Type: application/json');
  echo json_encode(['status' => 'ok', 'items' => $items]);

  Копировать

• Хранение структурированных данных в файле или текстовой колонке базы данных вместо serialize(). JSON портативен между языками; serialize() работает только в PHP.

• Передача данных в JavaScript, отображаемый на странице, поскольку корректный JSON является корректным синтаксисом объекта JavaScript.

Заключение

json_encode() превращает массивы и объекты PHP в компактную, портативную JSON-строку. Используйте JSON_PRETTY_PRINT и JSON_UNESCAPED_UNICODE, когда вывод будет читать человек, защищайтесь от некорректных входных данных, проверяя возвращаемое значение или используя JSON_THROW_ON_ERROR, и помните, что кодируются только публичные свойства объектов. Для разбора JSON обратно в PHP используйте json_decode(); для общего обзора смотрите Работа с JSON в PHP.

Практика