PHP JSON

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

PHP поставляется с поддержкой JSON в ядре (расширение ext-json включено по умолчанию начиная с PHP 8.0), поэтому ничего дополнительно устанавливать не нужно.

Как выглядит JSON

JSON представляет данные в виде пар ключ-значение внутри объектов ({ }) и упорядоченных списков внутри массивов ([ ]). Значениями могут быть строки, числа, булевы значения, null, массивы или вложенные объекты:

{
  "name": "John",
  "age": 30,
  "active": true,
  "roles": ["admin", "editor"]
}

Две функции, которые вы будете использовать почти всегда:

• json_encode($value) — PHP-значение → JSON-строка (сериализация).
• json_decode($json) — JSON-строка → PHP-значение (десериализация).

Кодирование: из PHP в JSON с помощью json_encode

json_encode() преобразует PHP-значение — как правило, массив или объект — в JSON-строку.

Кодирование ассоциативного массива

Ассоциативный массив преобразуется в JSON-объект, тогда как индексированный массив (последовательные целочисленные ключи, начиная с 0) становится JSON-массивом:

<?php

echo json_encode(["red", "green", "blue"]);
// ["red","green","blue"]

?>

Форматирование вывода

По умолчанию json_encode создаёт компактный JSON в одну строку, что идеально подходит для передачи по сети. Если вам нужен читаемый вывод (для логирования или отладки), передайте флаг JSON_PRETTY_PRINT. Флаги объединяются с помощью побитового оператора |:

<?php

$data = [
    "user" => ["name" => "Jane", "roles" => ["admin", "editor"]],
    "active" => true,
];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

?>

Это выведет красиво оформленный JSON с отступами:

{
    "user": {
        "name": "Jane",
        "roles": [
            "admin",
            "editor"
        ]
    },
    "active": true
}

Другие полезные флаги: JSON_UNESCAPED_SLASHES (сохраняет / вместо \/) и JSON_UNESCAPED_UNICODE (сохраняет символы вроде é вместо é).

Декодирование: из JSON в PHP с помощью json_decode

json_decode() преобразует JSON-строку обратно в PHP-значение. По умолчанию возвращаются объекты, но если передать true вторым аргументом, вместо них будут возвращаться ассоциативные массивы — с ними обычно удобнее работать в циклах:

Без аргумента true вы получаете объект stdClass, а доступ к значениям осуществляется через стрелочную нотацию -> вместо [ ]:

Используйте true, если хотите получить массив; опустите этот аргумент, если предпочитаете синтаксис объекта. Оба варианта содержат одни и те же данные.

Кодирование пользовательского объекта

json_encode также работает с объектами. Когда вам нужно динамически построить JSON-структуру, пустой объект stdClass позволяет добавлять свойства на лету. (Для полноценных классов см. PHP-классы и объекты.)

Публичные свойства любого объекта включаются автоматически; приватные и защищённые свойства пропускаются, если только класс не реализует интерфейс JsonSerializable.

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

Разбор JSON может завершиться ошибкой — некорректная строка, незакрытая кавычка или завершающая запятая приведут к сбою декодирования. При неудаче json_decode возвращает null, поэтому необходимо отличать настоящее значение null от ошибки. Проверяйте json_last_error() (или читайте json_last_error_msg() для получения понятного сообщения):

<?php

$badJson = '{invalid}';
$result = json_decode($badJson);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "JSON error: " . json_last_error_msg();
    // JSON error: Syntax error
}

?>

Начиная с PHP 7.3 можно передавать флаг JSON_THROW_ON_ERROR, чтобы обе функции выбрасывали исключение JsonException, которое удобно обрабатывать в блоках try/catch:

<?php

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

?>

Примечание: у json_decode есть ограничение глубины (по умолчанию 512 уровней, третий аргумент). Очень глубоко вложенный JSON завершится ошибкой JSON_ERROR_DEPTH, если не увеличить это значение.

Типичный сценарий: чтение тела JSON-запроса

Когда клиент отправляет JSON на PHP-эндпоинт (как это делает большинство API), тело запроса поступает как необработанные данные, а не через $_POST. Прочитайте его с помощью php://input и декодируйте:

<?php

$body = file_get_contents("php://input");
$data = json_decode($body, true);

// echo a JSON response back to the client
header("Content-Type: application/json");
echo json_encode(["received" => $data]);

?>

Заключение

JSON — стандартный формат обмена данными в современных веб-приложениях, и PHP предоставляет удобные инструменты для работы с ним:

• Используйте json_encode для преобразования массивов и объектов в JSON; добавьте JSON_PRETTY_PRINT для читаемого вывода.
• Используйте json_decode для преобразования JSON обратно в PHP — передайте true для получения массива, опустите для получения объекта.
• Всегда проверяйте ошибки с помощью json_last_error() или JSON_THROW_ON_ERROR, прежде чем доверять декодированным данным.

С этими инструментами вы сможете уверенно обмениваться JSON-данными между вашим PHP-кодом, базами данных, браузерами и внешними веб-сервисами.

Практика