Функция json_decode в PHP — полное руководство

Функция json_decode в PHP превращает строку в формате JSON в нативное значение PHP, с которым можно читать и работать. Она является парной к json_encode, выполняющей обратное действие (значение PHP → строка JSON). К json_decode обращаются всякий раз, когда данные поступают в виде текста и с ними нужно работать: ответ REST API, payload вебхука, конфигурационный файл или столбец, хранящийся в базе данных.

В этой главе рассматриваются сигнатура функции, разница между декодированием в объект и в ассоциативный массив, поведение вложенных данных, параметры depth и flags, а также правильный способ обработки некорректных входных данных.

Что такое JSON?

JSON (JavaScript Object Notation) — лёгкий текстовый формат обмена данными, удобный для чтения людьми и разбора машинами. Он представляет данные в виде пар ключ-значение (объекты, записываются как {}) и упорядоченных списков (массивы, записываются как []), используя строки, числа, булевы значения и null в качестве скалярных значений. Поскольку почти каждый язык может создавать и потреблять его, JSON стал стандартным форматом для веб-API. Смотрите обзор PHP и JSON для общей картины.

Синтаксис

json_decode(string $json, ?bool $associative = null, int $depth = 512, int $flags = 0): mixed

Параметр	Назначение
`$json`	JSON-строка для декодирования. Должна быть валидным UTF-8.
`$associative`	`true` → возвращает ассоциативные массивы; `false`/`null` → возвращает объекты `stdClass`.
`$depth`	Максимально допустимая глубина вложенности (по умолчанию `512`). Декодирование более глубоких данных завершается ошибкой.
`$flags`	Битовая маска параметров, например `JSON_THROW_ON_ERROR`, `JSON_BIGINT_AS_STRING`.

Функция возвращает декодированное значение (array, stdClass, string, int, float, bool или null), либо null при ошибке.

Декодирование JSON-строки

Наиболее распространённый случай — декодирование JSON-объекта. Передайте true в качестве второго аргумента, чтобы получить обратно ассоциативный массив PHP.

Пример функции json_decode в PHP

php— editable, runs on the server

Здесь $json представляет имя, возраст и город человека. При передаче true функция json_decode строит массив PHP, поэтому результат таков:

Array
(
    [name] => John
    [age] => 30
    [city] => New York
)

Значения затем читаются с помощью синтаксиса массива, например $array['name']. Подробнее об этой структуре данных см. ассоциативные массивы.

Использование второго параметра

Второй параметр функции json_decode является необязательным, но его часто используют для управления типом возвращаемой переменной. Если второй параметр равен true, json_decode вернёт массив. Если второй параметр равен false (по умолчанию), json_decode вернёт объект.

Пример функции json_decode в PHP с объектами

php— editable, runs on the server

Когда $associative равно false (или опущено), json_decode возвращает объект stdClass. Значения читаются с помощью синтаксиса свойств объекта: $object->name, $object->age и т.д. Используйте эту форму, когда предпочтителен доступ в стиле объекта или когда результат будет передан в код, ожидающий объекты (см. классы и объекты PHP).

Декодирование вложенного JSON

JSON в реальных задачах, как правило, вложен. json_decode обрабатывает вложенность автоматически: каждый уровень становится вложенным массивом (при true) или вложенным объектом (при false).

<?php

$json = '{"user":{"name":"John","roles":["admin","editor"]}}';
$data = json_decode($json, true);

echo $data['user']['name'];      // John
echo "\n";
echo $data['user']['roles'][0];  // admin

?>

Внутренние JSON-объекты становятся внутренними массивами, а JSON-массивы ([...]) превращаются в индексированные массивы PHP, по которым можно итерироваться с помощью foreach.

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

Если строка, переданная в json_decode, не является валидным JSON, функция возвращает null. Однако null также является допустимым значением JSON, поэтому проверка if ($array === null) не позволяет отличить ошибку декодирования от успешного декодирования литерала null. Для корректной обработки ошибок проверяйте json_last_error() или используйте флаг JSON_THROW_ON_ERROR (PHP 7.3+).

Обработка ошибок json_decode в PHP

php— editable, runs on the server

В строке выше отсутствует закрывающая кавычка, поэтому json_last_error() не равно JSON_ERROR_NONE и сообщение объясняет, что пошло не так.

Начиная с PHP 7.3, более чистым вариантом является флаг JSON_THROW_ON_ERROR, который выбрасывает исключение JsonException вместо молчаливого возврата null:

<?php

try {
    $data = json_decode('{"invalid": }', true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo "Could not decode JSON: " . $e->getMessage();
}

?>

Это позволяет обрабатывать некорректные входные данные с помощью стандартных блоков try/catch вместо ручной проверки результата после каждого вызова.

Связанные функции

json_encode — преобразование значения PHP в JSON-строку.
PHP и JSON — обзор работы с JSON в PHP.
Справочник PHP JSON — полный список JSON-функций и констант PHP.

Заключение

Функция json_decode в PHP — мощный инструмент для работы с данными JSON. Она быстра, надёжна и проста в использовании. Понимая детали работы json_decode и её второго параметра, вы сможете уверенно декодировать JSON-строки и использовать полученные данные в своих PHP-приложениях.

Практика

Что делает функция json_decode() в PHP?

Преобразует JSON-строку в переменную PHP.Декодирует данные в кодировке base64.Преобразует HTML-символы в их сущности.Позволяет передавать true в качестве второго аргумента для преобразования JSON-объектов в ассоциативные массивы.