PHPTime

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, nullstring, bool, nullТе же типы
42, 3.5int, 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
<?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
<?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
<?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
<?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
<?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
<?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

  1. На границе приложения используйте JSON_THROW_ON_ERROR для разбора и кодирования.
  2. Проверьте корневой тип, обязательные поля и типы значений после json_decode().
  3. Перед отправкой списка убедитесь, что его индексы последовательны. Проверьте отдельно пустые списки и объекты.
  4. Передавайте идентификаторы строками, если важны ведущие нули, точность и стабильный тип.
  5. Ограничьте размер запроса и глубину вложенности. Проверьте в тестах пустое тело, корректный null, некорректный UTF-8 и массив с пропущенным индексом.
  6. Сначала сформируйте тело ответа, затем установите 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-строку.

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

Ещё в разделе «Справочник PHP»

Ассоциативные и многомерные массивы в PHP

Как создавать ассоциативные и многомерные массивы в PHP, читать вложенные данные, получать ключи и значения через array_keys() и array_values().

10 мин

Вывод ошибок в PHP: display_errors, error_reporting и логи

Как включить вывод ошибок PHP через display_errors и ini_set, настроить error_reporting и error_log, найти логи и разобраться с deprecated в PHP 8.3–8.5.

9 мин

Дата и время в PHP: date, DateTime и часовые пояса

Как получить текущую дату и время в PHP, настроить часовой пояс, разобрать строку и отформатировать дату с date(), strtotime() и DateTimeImmutable.

8 мин

Загрузка файлов на сервер в PHP: $_FILES и безопасность

Как принять файл через $_FILES, проверить размер, MIME-тип и расширение, сохранить его вне публичной папки, выдать на скачивание и обработать ZIP.

10 мин