Справочник по JSON-функциям PHP

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

PHP поставляется с небольшим набором встроенных функций — так называемым расширением JSON — которые преобразуют PHP-значения в JSON-текст и обратно. Эта страница является кратким справочником по этим функциям и наиболее полезным константам опций. Пошаговое руководство см. в PHP JSON.

Когда использовать JSON в PHP?

Эти функции нужны всякий раз, когда данные должны покинуть PHP в виде текста или прийти в виде текста:

• Возврат данных из конечной точки API (echo json_encode($data);).
• Чтение тела запроса или конфигурационного файла в формате JSON.
• Хранение структурированного значения (например, массива настроек) в одном столбце базы данных или ключе кэша.
• Взаимодействие со сторонним веб-сервисом, который работает с JSON.

Расширение JSON включено по умолчанию в PHP 5.2 и выше, а в PHP 8.0+ оно является частью ядра, поэтому установка не требуется.

JSON-функции

json_encode()

json_encode() сериализует PHP-значение в строку в формате JSON.

<?php

$data = [
    "name"  => "Ada",
    "age"   => 36,
    "langs" => ["PHP", "JS"],
];

echo json_encode($data);

?>

Вывод:

{"name":"Ada","age":36,"langs":["PHP","JS"]}

Обратите внимание: ассоциативный массив становится JSON-объектом {}, а массив-список (["PHP","JS"]) — JSON-массивом []. Полный справочник см. в json_encode().

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

Передайте опцию JSON_PRETTY_PRINT, чтобы результат был читаемым:

<?php

$data = ["name" => "Ada", "langs" => ["PHP", "JS"]];

echo json_encode($data, JSON_PRETTY_PRINT);

?>

Вывод:

{
    "name": "Ada",
    "langs": [
        "PHP",
        "JS"
    ]
}

json_decode()

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

<?php

$json = '{"name":"Ada","age":36,"langs":["PHP","JS"]}';

// Decode as an associative array
$data = json_decode($json, true);

echo $data["name"];   // Ada
echo "\n";
echo $data["langs"][0]; // PHP

?>

Вывод:

Ada
PHP

Полный справочник см. в json_decode().

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

json_encode() возвращает false, а json_decode() возвращает null, когда что-то идёт не так (неверная кодировка UTF-8, синтаксическая ошибка во входных данных или вложенность глубже лимита). Поскольку null также является допустимым декодированным значением, всегда проверяйте json_last_error(), а не только тестируйте на null.

<?php

$bad = '{"name": "Ada", }';   // trailing comma is invalid JSON

$result = json_decode($bad, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "Invalid JSON: " . json_last_error_msg();
} else {
    echo "Decoded fine.";
}

?>

Вывод:

Invalid JSON: Syntax error

В PHP 7.3+ можно передать флаг JSON_THROW_ON_ERROR в обе функции, чтобы получить JsonException вместо ручной проверки кода ошибки.

Часто используемые константы опций

Эти битмask-константы передаются в аргументе $options функции json_encode() (некоторые применимы и к json_decode()):

• JSON_PRETTY_PRINT — форматирует вывод с отступами и пробелами.
• JSON_UNESCAPED_SLASHES — оставляет символы / без экранирования (http:// вместо http:\/\/).
• JSON_UNESCAPED_UNICODE — сохраняет многобайтовые символы как есть, вместо escaping в виде \uXXXX.
• JSON_THROW_ON_ERROR — выбрасывает JsonException при ошибке (PHP 7.3+).
• JSON_FORCE_OBJECT — всегда генерирует JSON-объект, даже для последовательного массива.

Комбинируйте их с помощью оператора побитового ИЛИ:

<?php

$data = ["site" => "https://www.w3docs.com", "name" => "café"];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

?>

Вывод:

{
    "site": "https://www.w3docs.com",
    "name": "café"
}

Связанные темы

• PHP JSON — полное вводное руководство.
• PHP Arrays и Associative Arrays — структуры, которые наиболее естественно соответствуют JSON.
• PHP Functions — как обернуть encode/decode в собственные вспомогательные функции.

Практика