JSON в PHP: json_encode, json_decode и обработка ошибок
PHP преобразует массивы, объекты и скалярные значения в JSON с помощью json_encode(), а разбирает JSON через json_decode(). Разберём, как сохранить форму данных, отличить ошибку от допустимого null и вернуть JSON с нужным HTTP-статусом.
JSON в PHP — как значения переходят между форматами
json_encode() принимает значение PHP и возвращает JSON-строку. json_decode() принимает JSON-строку и возвращает значение PHP. Корнем JSON может быть объект, массив, строка, число, логическое значение или null. Если ваш API принимает только объект с определёнными полями, это требование нужно проверить после разбора.
| JSON | При декодировании по умолчанию | С associative: true |
|---|---|---|
{"id":42} | stdClass | Ассоциативный массив |
[1,2] | Массив со списочными индексами | Массив со списочными индексами |
"текст", true, null | string, bool, null | Те же типы |
42, 3.5 | int, float | Те же типы |
Целые числа, выходящие за диапазон int, по умолчанию могут стать float с потерей точности. Для таких значений предусмотрен флаг JSON_BIGINT_AS_STRING.
PHP JSON encode — как работает json_encode()
Используйте JSON_THROW_ON_ERROR, чтобы при сбое получить JsonException. JSON_UNESCAPED_UNICODE оставляет кириллицу читаемой, а JSON_PRETTY_PRINT добавляет отступы. Экранированная кириллица и обычный UTF-8 при декодировании дают одну и ту же строку.
<?php
declare(strict_types=1);
$product = ['id' => 42, 'name' => 'Кофе', 'tags' => ['зерно']];
// При ошибке кодирования будет выброшено JsonException.
$json = json_encode($product, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
echo $json;
// {"id":42,"name":"Кофе","tags":["зерно"]}Когда массив превращается в объект
PHP кодирует массив как JSON-список, если его ключи идут от 0 подряд в порядке обхода. Строковые ключи или пропуски в индексах дают JSON-объект. После array_filter() или unset() вызовите array_values(), если по контракту нужен список. Для пустого объекта можно передать new stdClass(). Флаг JSON_FORCE_OBJECT преобразует в объекты и вложенные списки, поэтому для одного пустого поля удобнее явно задать его значение.
<?php
declare(strict_types=1);
$items = ['чай', 'кофе', 'какао'];
unset($items[1]);
// Сохранившиеся ключи 0 и 2 дают JSON-объект.
echo json_encode($items, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE), PHP_EOL;
// {"0":"чай","2":"какао"}
echo json_encode(array_values($items), JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
// ["чай","какао"]У обычных объектов json_encode() сериализует публичные свойства. Для явного контроля полей реализуйте JsonSerializable и возвращайте нужные данные из jsonSerialize(). Если важно вывести 12.0 вместо 12, добавьте JSON_PRESERVE_ZERO_FRACTION. Этот флаг сохраняет дробную часть в записи числа, а точность вычислений по-прежнему зависит от типа значения.
json_decode() в PHP — массивы, объекты и большие числа
Параметр associative: true возвращает JSON-объекты как ассоциативные массивы. С associative: false они становятся объектами stdClass, а JSON-списки остаются массивами. Это удобно, когда нужно отличать {} от [] или точно сохранить форму данных при обратном кодировании. В режиме associative: true оба пустых значения становятся [], а объект с ключами "0", "1" при повторном кодировании может стать списком.
<?php
declare(strict_types=1);
$json = '{"id":123456789012345678901,"active":true}';
$data = json_decode(
$json,
associative: true,
depth: 32,
flags: JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING,
);
// Целое за пределами диапазона int сохранено без потери цифр.
var_dump($data['id']); // string(21) "123456789012345678901"JSON_BIGINT_AS_STRING применяется к целым числам за пределами диапазона int. Если идентификатор всегда должен быть строкой, задайте это в контракте API и передавайте его в кавычках. Тогда тип поля будет одинаковым и у коротких, и у длинных идентификаторов. По той же причине осторожно используйте JSON_NUMERIC_CHECK. Он может превратить строку "00123" в число 123 и убрать ведущие нули.
Параметр depth ограничивает глубину вложенности. Значение по умолчанию равно 512. Для запроса с простой структурой можно выбрать меньший предел. Размер тела, обязательные поля и типы значений проверяются отдельно. declare(strict_types=1) помогает соблюдать типы при вызовах функций, а структуру декодированного JSON нужно проверять явно.
Обработка ошибок JSON — JsonException и типичные причины
С JSON_THROW_ON_ERROR корректный JSON null возвращает PHP-значение null, а ошибка разбора вызывает исключение. Это позволяет отличить допустимое значение от пустой строки, битого ввода или обрезанного тела запроса.
<?php
declare(strict_types=1);
foreach (['null', '{"id":42,}'] as $input) {
try {
var_dump(json_decode($input, flags: JSON_THROW_ON_ERROR));
} catch (JsonException $e) {
// В приложении запишите причину в журнал.
echo 'Ошибка JSON: ', $e->getMessage(), PHP_EOL;
}
}- Синтаксис. Имена свойств и строки в JSON заключаются в двойные кавычки. Комментарии и запятая после последнего элемента недопустимы. Для генерации JSON из PHP-данных используйте
json_encode(). - Кодировка. Строки для
json_encode()и входjson_decode()должны быть в UTF-8. Если исходная кодировка известна, преобразуйте данные на входе. Если допустима потеря отдельных символов,JSON_INVALID_UTF8_SUBSTITUTEзаменит некорректные последовательности символомU+FFFD. - Глубина. Слишком глубокий документ даёт ошибку
JSON_ERROR_DEPTH. Недопустимое значение аргументаdepthуjson_decode(), например0, приводит кValueError. Такой случай исправляют в коде вызова. - Данные, которые нельзя сериализовать. Циклические ссылки, ресурсы,
INFиNANприводят к ошибке кодирования. Нормализуйте такие значения в соответствии с контрактом API.
В коде без JSON_THROW_ON_ERROR json_encode() при ошибке обычно возвращает false, а json_decode() — null. Сразу после вызова читайте json_last_error() или json_last_error_msg(). Вызовы с JSON_THROW_ON_ERROR глобальное состояние ошибки не обновляют. У JSON_PARTIAL_OUTPUT_ON_ERROR приоритет над JSON_THROW_ON_ERROR, поэтому их сочетание может вернуть частичный ответ с подставленными значениями. Если ответ должен быть полным, используйте режим исключений без частичного вывода.
PHP header JSON — как прочитать запрос и отправить ответ
Сырой JSON из HTTP-запроса читайте через php://input. Заголовок Content-Type: application/json описывает формат тела. Для ответа вызовите header() до любого вывода, включая пробелы и BOM перед <?php. Сформируйте тело заранее, чтобы ошибка кодирования не застала обработчик после начала отправки ответа.
<?php
declare(strict_types=1);
// Пример обработчика, который принимает объект с полем name.
$raw = file_get_contents('php://input');
$status = 500;
$body = '{"error":"internal_error"}';
if ($raw !== false) {
try {
$data = json_decode($raw, depth: 32, flags: JSON_THROW_ON_ERROR);
$status = 422;
$body = '{"error":"name_required"}';
if ($data instanceof stdClass
&& is_string($data->name ?? null)
&& trim($data->name) !== '') {
$body = json_encode(['ok' => true], JSON_THROW_ON_ERROR);
$status = 200;
}
} catch (JsonException $e) {
$status = 400;
$body = '{"error":"invalid_json"}';
}
}
http_response_code($status);
header('Content-Type: application/json');
echo $body;В примере 400 означает, что тело не удалось разобрать с заданным пределом вложенности. 422 означает, что JSON разобран, но не соответствует требованиям к объекту и полю name. Успешный ответ состоит из фиксированного массива. Если обработчик кодирует данные из приложения, обрабатывайте ошибки кодирования отдельно от ошибок разбора запроса и возвращайте при сбое формирования ответа 500.
Если эндпоинт принимает исключительно JSON, проверьте входной Content-Type и верните 415 при неподдерживаемом типе. Учитывайте параметры заголовка, например application/json; charset=utf-8. Лимит размера тела задавайте на уровне веб-сервера или приложения. Если HTTP-заголовки уже отправлены, проверьте headers_sent() и найдите источник раннего вывода.
Отличия PHP 8.3–8.5 и применение json_validate()
На конец 2026 года для PHP 8.3 выходят исправления безопасности, а PHP 8.4 и 8.5 находятся на активной поддержке. Все три версии поддерживают JSON_THROW_ON_ERROR, именованные аргументы и json_validate(). Расширение JSON входит в PHP 8.x и всегда включено.
json_validate() появилась в PHP 8.3. Она проверяет синтаксис JSON и глубину вложенности без построения PHP-структуры. Это подходит, когда строку нужно сохранить или передать дальше в исходном виде. Если нужны поля документа, сразу вызывайте json_decode() с JSON_THROW_ON_ERROR. Предварительная валидация в этом случае разбирает строку дважды.
<?php
declare(strict_types=1);
$raw = '{"event":"created"}';
// Проверяем строку перед сохранением в исходном виде.
if (!json_validate($raw, depth: 32)) {
throw new RuntimeException(json_last_error_msg());
}Для json_validate() доступны flags: 0 и JSON_INVALID_UTF8_IGNORE. JSON_THROW_ON_ERROR эта функция не принимает. true подтверждает, что строка вроде 42 или null является допустимым JSON. Проверку схемы и типов выполняйте отдельно.
Чек-лист для работы с JSON в PHP
- На границе приложения используйте
JSON_THROW_ON_ERRORдля разбора и кодирования. - Проверьте корневой тип, обязательные поля и типы значений после
json_decode(). - Перед отправкой списка убедитесь, что его индексы последовательны. Проверьте отдельно пустые списки и объекты.
- Передавайте идентификаторы строками, если важны ведущие нули, точность и стабильный тип.
- Ограничьте размер запроса и глубину вложенности. Проверьте в тестах пустое тело, корректный
null, некорректный UTF-8 и массив с пропущенным индексом. - Сначала сформируйте тело ответа, затем установите HTTP-статус и
Content-Type: application/json, после чего отправьте тело.
Частые вопросы
Почему json_decode() возвращает null?
Для строки null это корректный результат. Без JSON_THROW_ON_ERROR такой же результат возможен при ошибке разбора. Добавьте JSON_THROW_ON_ERROR, чтобы ошибочный ввод вызывал JsonException, или проверьте json_last_error() сразу после вызова.
Почему json_encode() выводит объект вместо массива?
JSON-список получается из PHP-массива, ключи которого идут от 0 подряд в порядке обхода. После удаления или фильтрации элементов примените array_values(), если нужно восстановить последовательные индексы.
Какой заголовок нужен для JSON-ответа в PHP?
Вызовите header('Content-Type: application/json') до вывода тела. HTTP-статус задайте через http_response_code(), а в тело выведите JSON-строку.