PHP: полный мануал с примерами, функциями и ООП

JSON — общий текстовый формат для разных программ

PHP-массив живёт внутри PHP. Мобильное приложение, Node.js и контроллер на объекте не умеют читать его внутреннее устройство. Они договариваются передавать текст в известном формате — например JSON. json_encode создаёт такой текст из PHP-значения; json_decode читает текст и создаёт PHP-значение. Ни одна из этих функций сама не отправляет HTTP-запрос.

<?php
$stock = 0;
$text = json_encode($stock);
var_dump($text);
$restored = json_decode($text);
var_dump($restored);

string(1) "0"
int(0)

Если вы ещё не работали с вложенными структурами, сначала пройдите JSON-текст → массив → чтение полей. Далее этот справочник раскрывает весь договор расширения, а не заменяет начальный урок сложным примером.

Какие значения можно передавать

<?php
var_dump(json_decode('null'));
var_dump(json_decode('false'));
var_dump(json_decode('"0041"'));
var_dump(json_decode('[4, 1]'));

NULL
bool(false)
string(4) "0041"
array(2) {
  [0]=>
  int(4)
  [1]=>
  int(1)
}

Синтаксически верный документ ещё не заказ. Приложение отдельно требует объект, ключи, типы, диапазоны и доступ к данным. Повторяющиеся имена полей опасны при обмене между разными парсерами: PHP оставляет последнее значение. JSON-функции не дают встроенного режима «запретить дубликаты имён». Не проверяйте это регулярным выражением; для соответствующего протокола нужен парсер с такой политикой.

Установка, версии и точность чисел

В PHP 8 JSON является обязательным расширением и всегда включён. В более старых сборках его можно было отключить. json_encode/json_decode появились в PHP 5.2, json_last_error — 5.3, JsonSerializable — 5.4, текст ошибки — 5.5, JsonException и JSON_THROW_ON_ERROR — 7.3, json_validate — 8.3. Примеры последней функции требуют PHP 8.3+.

<?php
var_dump(extension_loaded("json"));
var_dump(function_exists("json_validate"));

bool(true)
bool(true)

С PHP 7.1 формат float при кодировании зависит от serialize_precision; обычное значение −1 выбирает необходимое представление. Это не делает двоичные дроби точной десятичной арифметикой. Деньги передавайте целыми минимальными единицами или согласованной десятичной строкой. Большой ID лучше объявлять строкой ещё в API: JSON_BIGINT_AS_STRING защищает только целые числа при декодировании в PHP и не исправит точность, уже потерянную источником.

Две модели ошибки: результат или исключение

У json_encode без специальных флагов ошибка возвращает false; у json_decode — null. Но null бывает и правильным JSON-значением. В старом стиле сразу после вызова читают json_last_error. В новом коде удобно указать JSON_THROW_ON_ERROR и перехватить JsonException: успешный null тогда не смешивается с ошибкой разбора.

<?php
foreach (['null', '{broken'] as $body) {
    try {
        $data = json_decode($body, true, 16, JSON_THROW_ON_ERROR);
        var_dump($data);
    } catch (JsonException $error) {
        echo "Документ не разобран\n";
        var_dump($error->getCode() === JSON_ERROR_SYNTAX);
    }
}

NULL
Документ не разобран
bool(true)

У json_decode и json_validate значение depth вне допустимого диапазона даёт ValueError — это ошибка настройки вызова, а не испорченный документ. У json_encode поведение другое: превышение предела при обходе структуры относится к JSON_ERROR_DEPTH; скаляр вообще не требует такого обхода. Задавайте положительный предел и не рассчитывайте на общий для всех функций ValueError. Нарушение типа параметра может дать TypeError. Пользовательский jsonSerialize способен сам выбросить исключение; JSON_THROW_ON_ERROR не превращает все ошибки приложения в JsonException. Подробности try/catch и исключений нужны после первого понятного вызова, а не вместо него.

JsonException: что хранится в объекте ошибки

JsonException наследует Exception. Его создаёт JSON-операция с JSON_THROW_ON_ERROR при ошибке данных. Наследование здесь полезно: у разных ошибок общий способ получить сообщение, код, файл и цепочку причин. Приложение может обработать именно JSON-сбой, а выше по уровню — общий сбой импорта.

Служебные свойства message, code, file, line защищены, string, trace, previous закрыты. Читайте их указанными методами. Смысл этих областей видимости одинаков и в собственных классах.

<?php
function readSupplierPayload(string $body): mixed
{
    try {
        return json_decode($body, true, 32, JSON_THROW_ON_ERROR);
    } catch (JsonException $cause) {
        throw new RuntimeException("Поставщик вернул неверный JSON", 0, $cause);
    }
}
try {
    readSupplierPayload('{broken');
} catch (RuntimeException $error) {
    echo $error->getMessage(), "\n";
    var_dump($error->getPrevious() instanceof JsonException);
}

Поставщик вернул неверный JSON
bool(true)

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

Флаг — именованное целое значение, включающее режим функции. Совместимые флаги объединяются побитовым |. Их номера не нужно запоминать или складывать вручную. У decode, encode и validate разные допустимые режимы.

<?php
$data = ["name" => "Болт", "path" => "/catalog/41"];
echo json_encode($data, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT);

{
    "name": "Болт",
    "path": "/catalog/41"
}

<?php
echo json_encode(12.0), "\n";
echo json_encode(12.0, JSON_PRESERVE_ZERO_FRACTION);

12
12.0

<?php
$data = ["sku" => "0041", "quantity" => 2];
echo json_encode($data, JSON_THROW_ON_ERROR), "\n";
echo json_encode($data, JSON_THROW_ON_ERROR | JSON_NUMERIC_CHECK);

{"sku":"0041","quantity":2}
{"sku":41,"quantity":2}

<?php
$data = ["filters" => (object) [], "items" => []];
echo json_encode($data, JSON_THROW_ON_ERROR), "\n";
echo json_encode($data, JSON_THROW_ON_ERROR | JSON_FORCE_OBJECT);

{"filters":{},"items":[]}
{"filters":{},"items":{}}

<?php
$text = "A\xFFB";
echo json_encode($text, JSON_INVALID_UTF8_IGNORE), "\n";
echo json_encode($text, JSON_INVALID_UTF8_SUBSTITUTE);

"AB"
"A\ufffdB"

<?php
$data = ["ratio" => INF];
echo json_encode($data, JSON_THROW_ON_ERROR | JSON_PARTIAL_OUTPUT_ON_ERROR), "\n";
var_dump(json_last_error() === JSON_ERROR_INF_OR_NAN);

{"ratio":0}
bool(true)

Все категории JSON_ERROR_*

Код ошибки полезен для машинного решения, текст — для диагностики. Не публикуйте весь документ, трассировку и токены в сообщении посетителю. Ошибка UTF-16 здесь относится к последовательности \uXXXX внутри JSON, а не к разрешению отправлять JSON-файл в UTF-16.

<?php
$cases = [
    ['{"a":}', 16, JSON_ERROR_SYNTAX],
    ['"' . "\xFF" . '"', 16, JSON_ERROR_UTF8],
    ['[[[1]]]', 2, JSON_ERROR_DEPTH],
    ['"\uD800"', 16, JSON_ERROR_UTF16],
];
foreach ($cases as [$body, $depth, $expectedCode]) {
    json_decode($body, true, $depth);
    var_dump(json_last_error() === $expectedCode);
}

bool(true)
bool(true)
bool(true)
bool(true)

Как объект определяет публичное JSON-представление

Без специального договора json_encode берёт публичные свойства объекта. Если нужны другие имена полей, вычисленные значения или стабильный внешний формат, класс реализует интерфейс JsonSerializable. Интерфейс требует публичный метод jsonSerialize без параметров. Этот метод возвращает PHP-данные, которые затем кодирует json_encode.

JSON-объект и PHP-объект класса — разные понятия. Для начала не нужен собственный класс: массив отлично подходит для простого ответа. Метод полезен, когда формат повторяется у многих экземпляров. JsonSerializable::jsonSerialize содержит минимальный класс, вложенный ответ и объяснение каждого шага.

Граница интеграции: синтаксис, схема и транспорт

Сначала проверьте статус HTTP, размер тела и ожидаемый Content-Type. Затем разбирайте JSON и проверяйте структуру данных. Успех HTTP не гарантирует полезный JSON, а верный JSON не гарантирует нужные поля. Ошибку авторизации в виде HTML не надо «исправлять», вырезая участок от первой фигурной скобки.

<?php
$body = "\xEF\xBB\xBF" . '{"stock":0}';
if (str_starts_with($body, "\xEF\xBB\xBF")) {
    $body = substr($body, 3);
}
$data = json_decode($body, true, 16, JSON_THROW_ON_ERROR);
echo $data['stock'];

0

Не вызывайте stripslashes, html_entity_decode или «очистку всех управляющих» наугад: это меняет допустимые данные и способно сломать экранирование. Если источник прислал JSON внутри JSON-строки, нужно подтвердить такой договор, а не декодировать многократно до исчезновения ошибки. Диагностика реального ответа показывает дальнейший разбор.

Декодирование требует памяти для исходного текста и структуры; последующее encode создаёт ещё одну строку. Не загружайте огромный архив как одно тело без лимитов. Для больших потоков выбирайте согласованный построчный формат, пагинацию или специализированный потоковый парсер. JSON-функции из этой категории целиком обрабатывают переданное значение.

• Нужно число из поля stock: decode с ошибкой, затем проверить объект/массив, наличие поля, int и допустимый диапазон.
• Нужно только проверить JSON-файл перед хранением: validate подходит, но лимит размера и доверие к содержимому остаются отдельными.
• После array_filter клиент видит объект вместо списка: если ключи технические, восстановить array_values; если это словарь, ключи сохранять.
• После encode у телефона пропал + или нули: убрать NUMERIC_CHECK, проверить типы исходных полей.
• Для повторяемого формата ответа объекта: JsonSerializable возвращает выбранный массив, json_encode вызывается один раз снаружи.

Все функции и интерфейс JSON

• json_decode
• json_encode
• json_last_error
• json_last_error_msg
• json_validate
• JsonSerializable::jsonSerialize