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

Массив внутри массива: собрать два отдельных списка на сборку

Два покупателя заказали разный набор напитков. Первый — чай и кофе, второй — какао. Нужно держать оба заказа вместе, сохранив границу каждого. Обычный массив хранит несколько значений; одним из этих значений может быть другой массив. Так получается вложенная структура. Сначала запишем один простой список, затем поместим списки в общий набор.

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

<?php
$order = ['Чай', 'Кофе'];
echo 'Первый напиток: ', $order[0], "\n";
echo 'Второй напиток: ', $order[1], "\n";

Первый напиток: Чай
Второй напиток: Кофе

<?php
$orders = [
    ['Чай', 'Кофе'],
    ['Какао'],
];
echo 'Заказ 1, напиток 2: ', $orders[0][1], "\n";
echo 'Заказ 2, напиток 1: ', $orders[1][0], "\n";

Заказ 1, напиток 2: Кофе
Заказ 2, напиток 1: Какао

Все данные сейчас созданы в самом PHP. Для появления вложенности не нужны JSON, база данных или внешний сервис. Сначала освоим ключи и обход такой структуры, затем узнаем, как она может прийти из внешнего текста.

Каждый ключ — отдельный шаг: прочитать, скопировать, изменить

Если в выражении несколько [] подряд, читайте слева направо. Можно разложить путь на промежуточную переменную: взять первый заказ целиком, затем выбрать кофе. Вопрос о получении значения из многомерного массива возникает именно здесь: внешняя структура и нужная строка — разные значения.

<?php
$orders = [['Чай', 'Кофе'], ['Какао']];
$firstOrder = $orders[0];
$secondDrink = $firstOrder[1];
echo 'Через промежуточный список: ', $secondDrink, "\n";
echo 'Прямым путём: ', $orders[0][1], "\n";

Через промежуточный список: Кофе
Прямым путём: Кофе

Промежуточное присваивание обычного массива даёт отдельное значение. Если покупатель заменил кофе на какао, записывайте по полному пути в исходный orders либо явно присвойте изменённую копию назад. Сначала увидим обе ситуации.

<?php
$orders = [['Чай', 'Кофе'], ['Какао']];
$firstOrder = $orders[0];
$firstOrder[1] = 'Какао';
echo 'Копия: ', $firstOrder[1], "\n";
echo 'Исходный заказ до записи: ', $orders[0][1], "\n";
$orders[0][1] = 'Какао';
echo 'Исходный заказ после записи: ', $orders[0][1], "\n";
echo 'Другой заказ: ', $orders[1][0], "\n";

Копия: Какао
Исходный заказ до записи: Кофе
Исходный заказ после записи: Какао
Другой заказ: Какао

У отсутствующего ключа прямое чтение выдаёт предупреждение. Не добавляйте [0] наугад, пока строка не появится. Сначала определите структуру. Для действительно необязательного поля оператор ?? выбирает резерв при отсутствии или null; для обязательного элемента это способ спрятать ошибку, если договор не предусматривает резерв.

Внешний foreach получает один внутренний массив за проход

Для сборщика нужна ведомость каждого заказа. Известно, что в каждом заказе есть первый напиток, поэтому сначала обойдём только внешние элементы. foreach ($orders as $order) берёт очередное значение внешнего массива; поскольку этим значением является массив, местная $order содержит целый внутренний список.

<?php
$orders = [['Чай', 'Кофе'], ['Какао']];
foreach ($orders as $order) {
    echo 'Первый напиток заказа: ', $order[0], "\n";
}
echo "Первые позиции проверены\n";

Первый напиток заказа: Чай
Первый напиток заказа: Какао
Первые позиции проверены

Вложенный массив не требует автоматически двух циклов. Число циклов зависит от задачи: если нужно известное поле или известный номер, достаточно прямого обращения. Если нужно каждое значение каждого заказа — переходим к двум циклам.

Два foreach: полностью собрать первый заказ, затем перейти ко второму

Теперь ведомость должна включать все напитки. Внешний цикл берёт номер и внутренний список; внутренний перебирает напитки этого списка. as $orderIndex => $order даёт ключ и значение. Номер для человека получаем как индекс + 1: программный ключ 0 соответствует первому заказу.

<?php
$orders = [['Чай', 'Кофе'], ['Какао']];
foreach ($orders as $orderIndex => $order) {
    $orderNumber = $orderIndex + 1;
    echo 'Заказ ', $orderNumber, "\n";
    foreach ($order as $drink) {
        echo '  Подготовить: ', $drink, "\n";
    }
    echo "Заказ собран\n";
}

Заказ 1
  Подготовить: Чай
  Подготовить: Кофе
Заказ собран
Заказ 2
  Подготовить: Какао
Заказ собран

Используйте разные понятные имена для уровней: orders → order → drink. Если внутреннее значение тоже назвать order, текущее значение внешнего цикла будет затёрто в теле. Если drink само оказалось массивом, задача имеет дополнительный уровень, который этот конкретный вывод строк ещё не обрабатывает.

Карточки по артикулам: структура отражает задачу магазина

Для реального каталога одного названия мало: у товара есть цена и остаток. Соберём карточки с ключами title, price, stock, затем поместим их во внешний словарь по артикулу. Строка TEA-01 теперь внешний ключ, а title — ключ внутри выбранной карточки.

<?php
$products = [
    'TEA-01' => ['title' => 'Чай', 'price' => 150, 'stock' => 3],
    'COF-02' => ['title' => 'Кофе', 'price' => 200, 'stock' => 2],
];
foreach ($products as $sku => $product) {
    echo $sku, ' — ', $product['title'], ': ', $product['price'], ' руб.; остаток ', $product['stock'], "\n";
}

TEA-01 — Чай: 150 руб.; остаток 3
COF-02 — Кофе: 200 руб.; остаток 2

Выбор структуры меняет удобную операцию: список хранит порядок, словарь позволяет обратиться к товару по известному артикулу. Два одинаковых строковых ключа не создают две карточки — последнее значение заменяет прежнее. Если повторные позиции должны сохраняться отдельно, нужен список записей с полем sku.

Три уровня: склад → товар → поле; число циклов выбирает задача

Один товар лежит на двух складах. Добавим внешний словарь складов, сохранив внутри привычный каталог. Теперь путь до остатка состоит из трёх ключей: south выбирает склад, TEA-01 выбирает товар, stock выбирает число. На каждом промежуточном шаге результат ещё массив.

<?php
$warehouses = [
    'north' => ['TEA-01' => ['title' => 'Чай', 'stock' => 3]],
    'south' => [
        'TEA-01' => ['title' => 'Чай', 'stock' => 8],
        'COF-02' => ['title' => 'Кофе', 'stock' => 2],
    ],
];
echo 'Чай на южном складе: ', $warehouses['south']['TEA-01']['stock'], "\n";
foreach ($warehouses as $warehouseName => $products) {
    foreach ($products as $sku => $product) {
        echo $warehouseName, ' / ', $sku, ': ', $product['stock'], ' уп.', "\n";
    }
}

Чай на южном складе: 8
north / TEA-01: 3 уп.
south / TEA-01: 8 уп.
south / COF-02: 2 уп.

Если инструмент диагностики должен перечислить все поля, потребуется третий foreach по product. Перед ним важно знать, что конечные значения — строки и числа: произвольный массив или объект нельзя без разбора превращать в строку.

<?php
$warehouses = [
    'north' => ['TEA-01' => ['title' => 'Чай', 'stock' => 3]],
    'south' => ['COF-02' => ['title' => 'Кофе', 'stock' => 2]],
];
foreach ($warehouses as $warehouseName => $products) {
    foreach ($products as $sku => $product) {
        foreach ($product as $field => $value) {
            echo $warehouseName, ' / ', $sku, ' / ', $field, ': ', $value, "\n";
        }
    }
}

north / TEA-01 / title: Чай
north / TEA-01 / stock: 3
south / COF-02 / title: Кофе
south / COF-02 / stock: 2

Пять ключей: длинный путь можно прочитать без догадок

В пакете каталога рядом со складами могут находиться дата обновления и другие сведения. У склада могут быть адрес и товары. Поэтому осмысленные промежуточные поля warehouses и products добавляют уровни. Посмотрите на полную запись и прочитайте путь по одному ключу.

<?php
$catalog = [
    'warehouses' => [
        'north' => [
            'products' => [
                'TEA-01' => ['stock' => 3],
            ],
        ],
    ],
];
$available = $catalog['warehouses']['north']['products']['TEA-01']['stock'];
$requested = 2;
if ($available >= $requested) {
    echo 'Северный склад выдаст ', $requested, ' уп.; после выдачи останется ', $available - $requested, "\n";
} else {
    echo "На северном складе недостаточно товара\n";
}

Северный склад выдаст 2 уп.; после выдачи останется 1

Не добавляйте уровни ради пяти пар скобок. У каждого контейнера должна быть роль. Если форма известна, точный путь самый прозрачный. Если глубина ветвей различается и заранее неизвестна, новый цикл для каждого возможного уровня перестаёт решать задачу; тогда изучают рекурсию.

Неизвестная глубина: одно правило для каждого внутреннего массива

Раздел каталога может содержать названия товаров и подразделы разной глубины. Для первого результата выведем все названия в порядке обхода: Чай, Кофе, Какао. Если очередное значение — массив, надо применить то же правило к нему. Если строка — вывести название. Это рекурсия: функция вызывает себя с меньшей частью исходной структуры.

До примера нужны параметр, вызов и возвращение управления. Объявление function showNames($items) задаёт местное имя items для текущего массива. При вызове showNames($catalog) в него попадает весь каталог, при внутреннем showNames($value) — только одна ветвь. У каждого вызова свой items и своё место внутри foreach.

Готовая функция is_array имеет договор is_array(mixed $value): bool: принимает любое значение и возвращает true для массива, false для прочих типов. Она ничего не печатает, не меняет вход и не углубляется сама. Наш if использует её ответ как выбор следующего действия. В этом первом дереве листья — только строки; произвольные внешние значения требуют дополнительной проверки.

<?php
function showNames($items)
{
    foreach ($items as $value) {
        if (is_array($value)) {
            showNames($value);
        } else {
            echo 'Товар: ', $value, "\n";
        }
    }
}
$catalog = ['Чай', ['Кофе', ['Какао']]];
showNames($catalog);
echo "Каталог просмотрен\n";

Товар: Чай
Товар: Кофе
Товар: Какао
Каталог просмотрен

Это развитие реальной задачи обхода заранее неизвестной глубины. Вопрос подсказал ситуацию; приведённое решение и объяснение написаны для этой главы. Рекурсия вводится после понимания структуры, а не вместо него.

Получить список из рекурсии и использовать его после вызова

Выводить во время обхода удобно для просмотра, но службе комплектации нужен готовый список: она сама решит, как подписать строки. Перепишем тот же обход с return. Каждый вызов создаёт свой пустой массив names. Строку добавляет в него сразу. Для вложенного массива получает готовый список branchNames и добавляет его названия по одному. После полного foreach возвращает собранный список.

<?php
function collectNames($items)
{
    $names = [];
    foreach ($items as $value) {
        if (is_array($value)) {
            $branchNames = collectNames($value);
            foreach ($branchNames as $name) {
                $names[] = $name;
            }
        } else {
            $names[] = $value;
        }
    }
    return $names;
}
$catalog = ['Чай', ['Кофе', ['Какао']], 'Печенье'];
$labels = collectNames($catalog);
foreach ($labels as $index => $title) {
    echo 'Этикетка ', $index + 1, ': ', $title, "\n";
}

Этикетка 1: Чай
Этикетка 2: Кофе
Этикетка 3: Какао
Этикетка 4: Печенье

Модель похожа на поручения: каждый помощник отдаёт список своей ветви тому, кто его попросил. В PHP никакие отдельные люди или параллельные процессы не создаются: это последовательные вложенные вызовы в одном выполнении. Незавершённые вызовы занимают стек и хранят своё состояние.

Сохранить путь: остаток 3 должен остаться остатком конкретного товара

Если собрать из складского дерева только числа, значения 3 и 8 потеряют адрес. Для отчёта добавим человеческий путь к каждой конечной величине. Параметр prefix получает уже пройденную часть, по умолчанию пустую строку. При переходе к очередному ключу добавляем его имя через точку — оператор соединения строк. Вложенный вызов получает новую часть пути, а предыдущий вызов сохраняет свой prefix.

<?php
function collectLines($items, $prefix = '')
{
    $lines = [];
    foreach ($items as $key => $value) {
        $path = $prefix . $key;
        if (is_array($value)) {
            $branchLines = collectLines($value, $path . ' / ');
            foreach ($branchLines as $line) {
                $lines[] = $line;
            }
        } else {
            $lines[] = $path . ': ' . $value;
        }
    }
    return $lines;
}
$catalog = [
    'warehouses' => [
        'north' => ['products' => ['TEA-01' => ['stock' => 3]]],
        'south' => ['products' => ['TEA-01' => ['stock' => 8]]],
    ],
    'status' => 'Обновлено',
];
$reportLines = collectLines($catalog);
echo "Сверка каталога\n";
foreach ($reportLines as $line) {
    echo $line, "\n";
}

Сверка каталога
warehouses / north / products / TEA-01 / stock: 3
warehouses / south / products / TEA-01 / stock: 8
status: Обновлено

Здесь формат результата — список строк для человека. Если ключ сам содержит « / », восстановить машинный путь по этой строке однозначно не получится: для машинного редактирования сохраняйте отдельный массив ключей. Договор листьев ограничен строками и числами; false и null требуют выбранного формата, объект или ресурс — отдельной политики. Пустой массив не создаёт строки отчёта: при необходимости показать пустые разделы это правило надо изменить явно.

Граница применимости: конечное дерево, допустимые листья и стоимость

Наши самостоятельные примеры получают заранее заданное конечное дерево массивов со строковыми или числовыми листьями. Условие is_array выбирает контейнер, но само по себе не доказывает, что структура конечна. Ссылкой PHP можно поместить массив внутрь самого себя; такой ввод короткий учебный обход не принимает. Не запускайте его на произвольных структурах без договора.

Каждый узел исходного дерева посещается при обходе. В варианте collectNames списки дочерних результатов дополнительно переносятся в списки родителей: работа зависит и от глубины, поэтому обещание «всегда линейно и быстро» здесь неверно. collectLines ещё создаёт строки путей. Для небольшого учебного дерева это помогает понимать возврат; большой импорт требует оценки памяти, пределов и выбранного способа накопления.

Если задача требует число конечных значений, можно возвращать целый накопитель вместо списка: для листа прибавлять 1, для массива прибавлять число, которое вернула его ветвь, а return поставить после foreach. Это другая метрика, чем count($data, COUNT_RECURSIVE): встроенная функция считает также элементы-контейнеры. Сумма чисел, число листьев, число товаров и число всех элементов — разные результаты; выбирайте их по требованию, а не по удобству функции.

В продолжении о рекурсии сохраняются отдельные темы пределов, циклических категорий, дерева по parent_id и явного стека. Рекурсивные итераторы и array_walk_recursive — другие инструменты: сравнивайте, дают ли они путь, контейнеры, листья и нужный способ изменения. Они не отменяют проверки смысла исходных данных.

Ограниченная глубина: вернуть весь список или объяснить отказ

Импортёр договорился принимать корневой массив и один уровень вложенных подразделов. Корень имеет depth = 0; первый внутренний массив — depth = 1. Более глубокую структуру нужно отклонить целиком. Обрезанный список нельзя выдавать за полный набор этикеток: товары исчезли бы без объяснения.

Сохраним уже знакомый collectNames, добавив параметры maxDepth и depth. Перед началом работы вызов сравнивает их. При превышении throw new RuntimeException(...) прекращает обычный путь; catch (RuntimeException $error) получает ошибку, а $error->getMessage() возвращает её сообщение. Эти конструкции подробно разобраны в уроке исключений. Здесь они показаны после работающей рекурсии и полного пути return.

<?php
function collectNamesLimited(array $items, int $maxDepth, int $depth = 0): array
{
    if ($depth > $maxDepth) {
        throw new RuntimeException('Подразделы глубже разрешённого уровня');
    }
    $names = [];
    foreach ($items as $value) {
        if (is_array($value)) {
            $branchNames = collectNamesLimited($value, $maxDepth, $depth + 1);
            foreach ($branchNames as $name) {
                $names[] = $name;
            }
        } else {
            $names[] = $value;
        }
    }
    return $names;
}
$labels = collectNamesLimited(['Чай', ['Кофе']], 1);
foreach ($labels as $title) {
    echo 'Подготовить этикетку: ', $title, "\n";
}
try {
    $deepLabels = collectNamesLimited(['Чай', ['Кофе', ['Какао']]], 1);
    foreach ($deepLabels as $title) {
        echo 'Подготовить дополнительную этикетку: ', $title, "\n";
    }
} catch (RuntimeException $error) {
    echo 'Второй каталог не принят: ', $error->getMessage(), "\n";
}

Подготовить этикетку: Чай
Подготовить этикетку: Кофе
Второй каталог не принят: Подразделы глубже разрешённого уровня

Входы этого примера — массивы со строковыми листьями, а maxDepth — заранее согласованное неотрицательное число. Тип array не проверяет вид листьев. Предел глубины гарантирует ограничение спусков по ветви, но не ограничивает количество соседей и память результата. Для реального внешнего пакета нужны также лимит размера, проверка формы и общий бюджет обхода. Нельзя выбрать единственную «безопасную глубину» для всех серверов и задач.

Упражнение: подставьте maxDepth = 0 для первого каталога. Чай будет добавлен в местный накопитель корня, но вход в [Кофе] вызовет отказ, и вызывающий код не получит частичный массив [Чай]. Для показа сообщения заключите и этот вызов в try/catch. Так проверяется отличие внутреннего промежуточного состояния от завершённого возвращаемого результата.

Практика: общий остаток одного артикула и следующий источник данных

На северном складе 3 упаковки чая, на южном 8. Нужен общий остаток TEA-01, а не сумма каждого встреченного числа в каталоге. Во всех складах этот товар есть, поля проверены. Достаточно перебрать склады и прочитать известный путь: результат должен равняться 11.

<?php
$warehouses = [
    'north' => ['TEA-01' => ['stock' => 3], 'COF-02' => ['stock' => 2]],
    'south' => ['TEA-01' => ['stock' => 8]],
];
$teaStock = 0;
foreach ($warehouses as $products) {
    $teaStock = $teaStock + $products['TEA-01']['stock'];
}
echo 'Чай на всех складах: ', $teaStock, ' уп.', "\n";

Чай на всех складах: 11 уп.

Мы уже умеем построить, прочитать, изменить и обойти многомерный массив в PHP. Теперь можно заменить источник: внешний сервис передаёт текст JSON, а json_decode получает из него значения PHP. После успешного разбора действуют те же ключи и циклы. Следующий материал про JSON добавляет формат обмена и обработку неудачи к уже понятной структуре.

JSON приходит текстом; массив появляется после разбора

Поставщик прислал текст карточки: название и остаток. Пока это строка, к полю stock нельзя обратиться как к элементу массива. JSON — формат обмена: объект записывается в фигурных скобках с именованными полями, список — в квадратных. Это не PHP-код, знак => внутри JSON не используется.

json_decode($json, true) выбирает представление JSON-объектов ассоциативными PHP-массивами. В примере также переданы предел вложенности 16 и флаг JSON_THROW_ON_ERROR: при неправильном JSON разбор бросит исключение. Эта константа — именованный режим функции, а не переменная. Первый опыт использует заранее известную корректную строку; приём неизвестного ответа потребует следующих проверок ниже.

<?php
$json = '{"title":"Чай","stock":3}';
$product = json_decode($json, true, 16, JSON_THROW_ON_ERROR);
echo $product['title'], "\n";
echo $product['stock'], "\n";

Чай
3

Попробуйте сами. Поменяйте stock на 0. Должно ли это считаться отсутствием поля?

Список карточек: каждый уровень читается отдельно

<?php
function knownCatalogUnits($json)
{
    $catalog = json_decode($json, true, 16, JSON_THROW_ON_ERROR);
    $total = 0;
    foreach ($catalog['items'] as $product) {
        $total += $product['stock'];
    }
    return $total;
}
$json = '{"items":[{"title":"Чай","stock":3},{"title":"Кофе","stock":2}]}';
echo knownCatalogUnits($json), "\n";

5

Путь к первому остатку — $catalog['items'][0]['stock']: поле → первый элемент → поле. Но внешняя система может прислать items = null, строку вместо числа или сообщение об ошибке вместо каталога. Следующая практическая секция превращает этот короткий опыт в надёжный приём: ограничивает размер, отличает JSON-объект от списка, проверяет каждый уровень и только затем записывает данные.

При associative=true некоторые различия исходных JSON-объектов и списков теряются. Когда договор требует именно JSON-список, одной последующей проверки array_is_list бывает недостаточно. Поэтому пример устройства ниже сначала сохраняет различие объектов и массивов, а затем строит проверенные данные. Ошибка формата ведёт в обработчик исключения.

Мини-ПК прислал показания: зачем JSON превращается в массив и обратно

Мини-ПК на объекте измерил температуру и влажность. Ему нужно передать показания вашему PHP-сервису, хотя программы работают на разных машинах и могут быть написаны на разных языках. По HTTP передаются байты. JSON даёт обеим сторонам понятный текстовый формат: имена полей, числа, строки, списки и вложенные объекты. Внутри PHP удобнее обращаться к массиву; при передаче следующему сервису снова нужен согласованный формат сообщения.

<?php
declare(strict_types=1);

$body = '{"device":"mini-01","readings":[{"sensor":"temperature","value":31.5},{"sensor":"humidity","value":0}]}';
if (strlen($body) > 4096) {
    throw new LengthException('Слишком большой пакет');
}
$wire = json_decode($body, false, 16, JSON_THROW_ON_ERROR);
if (!$wire instanceof stdClass || !is_array($wire->readings ?? null)) {
    throw new UnexpectedValueException('Нужен JSON-объект со списком readings');
}
$packet = (array) $wire;
if (!is_array($packet) || ($packet['device'] ?? null) !== 'mini-01'
    || !is_array($packet['readings'] ?? null) || !array_is_list($packet['readings'])
    || count($packet['readings']) < 1 || count($packet['readings']) > 20) {
    throw new UnexpectedValueException('Неверный пакет устройства');
}
$ranges = ['temperature' => [-50, 125], 'humidity' => [0, 100]];
$validated = [];
$seen = [];
foreach ($packet['readings'] as $reading) {
    if (!$reading instanceof stdClass) {
        throw new UnexpectedValueException('Показание должно быть JSON-объектом');
    }
    $reading = (array) $reading;
    if (!is_array($reading) || !is_string($reading['sensor'] ?? null)) {
        throw new UnexpectedValueException('Не указан датчик');
    }
    $sensor = $reading['sensor'];
    $value = $reading['value'] ?? null;
    if (!isset($ranges[$sensor]) || isset($seen[$sensor])
        || (!is_int($value) && !is_float($value)) || !is_finite((float) $value)
        || $value < $ranges[$sensor][0] || $value > $ranges[$sensor][1]) {
        throw new UnexpectedValueException('Недопустимое показание');
    }
    $seen[$sensor] = true;
    $validated[] = ['sensor' => $sensor, 'value' => $value];
}
$database = new PDO('sqlite::memory:', options: [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$database->exec('CREATE TABLE readings (device TEXT, sensor TEXT, value REAL)');
$insert = $database->prepare('INSERT INTO readings (device, sensor, value) VALUES (?, ?, ?)');
$database->beginTransaction();
try {
    foreach ($validated as $reading) {
        $insert->execute([$packet['device'], $reading['sensor'], $reading['value']]);
    }
    $database->commit();
} catch (Throwable $error) {
    if ($database->inTransaction()) { $database->rollBack(); }
    throw $error;
}
$reply = ['device' => $packet['device'], 'accepted' => count($validated)];
echo 'В базе: ', $database->query('SELECT COUNT(*) FROM readings')->fetchColumn(), "\n";
echo json_encode($reply, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE), "\n";

В базе: 2
{"device":"mini-01","accepted":2}

Здесь сначала выбран associative=false: JSON-объект остаётся stdClass, а JSON-список — массивом. Это позволяет отвергнуть объект с ключами "0", "1" вместо списка readings. При associative=true оба варианта могли бы стать одинаковым PHP-массивом, и array_is_list уже не доказывал бы исходный формат. После проверки мы явно превращаем нужный объект в массив через (array); такое приведение действует на один уровень, поэтому отдельное показание преобразуется внутри foreach. Это не универсальное преобразование произвольных классов.

Разбор JSON проверяет синтаксис, а следующий код — смысл. Строка "31.5" не принимается вместо числа по договору этого устройства, неизвестный датчик и повтор одного датчика в пакете отклоняются. Для другой модели допустима частичная приёмка, но тогда ответ должен перечислять принятые и отклонённые элементы: нельзя молча терять показания. Вложенные массивы здесь появились из реального списка readings, а не ради упражнения с квадратными скобками.

При превращении примера в HTTP endpoint потребуются отдельные шаги: проверка метода и Content-Type, ограниченное чтение тела, подтверждение устройства секретом или подписью, проверка принадлежности объекта, время измерения и ID пакета для защиты от повторного сохранения. Поле device в JSON само по себе ничего не доказывает. В примере нет аутентификации и дедупликации, поэтому готовым публичным endpoint он не является. Полный HTTP-контур показан в приёме вебхуков и самостоятельном проекте интеграции.

При отправке через Guzzle параметр json => $payload сам кодирует массив и готовит JSON-запрос. Передавать туда уже закодированную строку обычно ошибка: получится JSON-строка внутри JSON вместо ожидаемого объекта. Если тело сформировано вручную через json_encode, передают его как body с соответствующим Content-Type. Выбирайте один слой кодирования и проверяйте требования конкретного API: часть методов ожидает form-параметры или multipart, JSON не универсален.

Многомерный массив — отражение предметной области

Сервис доставки возвращает отправление, внутри получателя и список мест, внутри каждого места — товары. Маркетплейс возвращает список заказов, внутри каждого заказа позиции и адрес. JSON — текстовое представление этой структуры, а не готовая таблица. После json_decode(..., true) JSON-объекты становятся ассоциативными массивами, JSON-массивы — PHP-массивами списков. На каждом уровне вы обращаетесь к тому значению, которое находится именно там: $payload["orders"] — список, $order["items"] — другой список, $item["quantity"] — число.

Успешно декодировать JSON недостаточно. Текст null тоже корректен, но не подходит вместо объекта заказа. Поставщик может прислать HTML ошибки с HTTP 200 или изменить поле с числа на строку. JSON_THROW_ON_ERROR отличает ошибку синтаксиса от допустимого null; валидация схемы отличает допустимый JSON от нужных вам данных. Размер ответа ограничивают при чтении, глубину — при разборе. Не доверяйте случайной форме одного успешного ответа.

Проверяем каждый уровень, затем считаем

<?php
declare(strict_types=1);

$json = '{"orders":[{"id":"O-17","items":[{"sku":"A","quantity":2,"priceKopecks":15000},{"sku":"B","quantity":1,"priceKopecks":9900}]}]}';
$payload = json_decode($json, true, 32, JSON_THROW_ON_ERROR);
if (!is_array($payload) || !isset($payload['orders'])
    || !is_array($payload['orders']) || !array_is_list($payload['orders'])) {
    throw new UnexpectedValueException('orders должен быть списком');
}
foreach ($payload['orders'] as $orderIndex => $order) {
    if (!is_array($order) || !is_string($order['id'] ?? null)
        || !is_array($order['items'] ?? null) || !array_is_list($order['items'])) {
        throw new UnexpectedValueException("Заказ {$orderIndex}: неверная форма");
    }
    $total = 0;
    foreach ($order['items'] as $itemIndex => $item) {
        if (!is_array($item) || !is_string($item['sku'] ?? null)
            || !is_int($item['quantity'] ?? null) || $item['quantity'] < 1 || $item['quantity'] > 1000
            || !is_int($item['priceKopecks'] ?? null) || $item['priceKopecks'] < 0 || $item['priceKopecks'] > 100000000) {
            throw new UnexpectedValueException("Заказ {$orderIndex}, позиция {$itemIndex}: неверные данные");
        }
        $total += $item['quantity'] * $item['priceKopecks'];
    }
    echo $order['id'], ': ', $total, "\n";
}

O-17: 39900

Плохой JSON, большие ID и строки внутри JSON

<?php
declare(strict_types=1);

foreach (['{"orders":', 'null', '{"orders":[]}'] as $body) {
    try {
        $data = json_decode($body, true, 16, JSON_THROW_ON_ERROR);
        if (!is_array($data) || !is_array($data['orders'] ?? null)) {
            throw new UnexpectedValueException('Нужен объект со спискомorders');
        }
        echo "Контракт принят\n";
    } catch (JsonException $exception) {
        echo "НекорректныйJSON\n";
    } catch (UnexpectedValueException $exception) {
        echo "Не та структура\n";
    }
}

НекорректныйJSON
Не та структура
Контракт принят

Для идентификаторов больше PHP_INT_MAX используйте согласованный строковый контракт или JSON_BIGINT_AS_STRING при декодировании. Если поле metadata по договору содержит еще одну JSON-строку, декодируйте только это поле второй раз и снова проверяйте структуру. Не удаляйте обратные слеши заменой строк: так можно испортить законные кавычки, пути и содержимое текста. Произвольная рекурсивная попытка декодировать любую строку меняет типы там, где это не предусмотрено API.

Вернуть данные без изменения смысла

json_encode кодирует список с последовательными числовыми ключами как JSON-массив; пропуски после фильтрации могут дать объект. Восстанавливайте список через array_values только там, где действительно нужна последовательность. Не включайте JSON_NUMERIC_CHECK для произвольного ответа: телефон или артикул может потерять значимые символы. Все строки должны быть UTF-8. Не кодируйте объект домена целиком, если в нем есть секретные публичные свойства; соберите явное представление ответа.

Попробуйте сами. API прислал orders как объект с ID-ключами вместо списка. Исправлять array_values молча?

Плохой JSON в реальной интеграции: диагностировать и исправлять адресно

Интеграция вчера работала, а сегодня json_decode выбросил JsonException. Сначала проверьте HTTP-статус, Content-Type, размер, кодировку и характер первых байтов. Ответ может быть HTML-страницей авторизации, сообщением PHP Warning перед JSON, оборванным документом или UTF-8 BOM. Это разные причины, и одной «очисткой строки» их не исправить.

<?php
declare(strict_types=1);

function decodeKnownDevice(string $body): array
{
    if (strlen($body) > 4096) {
        throw new LengthException('Превышен предел тела');
    }
    if (str_starts_with($body, "\xEF\xBB\xBF")) {
        $body = substr($body, 3);
    }
    $packet = json_decode($body, true, 16, JSON_THROW_ON_ERROR);
    if (!is_array($packet) || !is_int($packet['value'] ?? null)) {
        throw new UnexpectedValueException('Нужен объект с целым value');
    }
    return $packet;
}
$samples = [
    'bom' => "\xEF\xBB\xBF" . '{"value":0}',
    'warning' => 'Warning: offline {"value":5}',
    'html' => '<html>Login required</html>',
    'truncated' => '{"value":',
    'utf8' => "{\"value\":\"\xFF\"}",
    'wrong-type' => '{"value":"5"}',
];
foreach ($samples as $name => $body) {
    try { echo $name, ': ', decodeKnownDevice($body)['value'], "\n"; }
    catch (JsonException) { echo "ошибка JSON\n"; }
    catch (UnexpectedValueException) { echo "неверная схема\n"; }
}

bom: 0
warning: ошибка JSON
html: ошибка JSON
truncated: ошибка JSON
utf8: ошибка JSON
wrong-type: неверная схема

Не используйте substr($body, strpos($body, '{')) как универсальное лечение: фигурная скобка может находиться в ошибке, корректный JSON может быть списком или скаляром, а повреждённый ответ останется повреждённым. Не удаляйте все обратные слеши: они могут экранировать кавычки внутри нормальной строки. Двойное декодирование нужно только для поля, которое по договору действительно содержит ещё одну JSON-строку.

Для диагностики полезны ID запроса, статус, размер, тип ответа и код ошибки разбора. Полное тело часто содержит токены и персональные данные. Если нужен фрагмент для отладки, используйте контролируемый журнал и предварительное удаление секретов. json_validate доступен с PHP 8.3, но перед json_decode обычно не нужен: это второй разбор тех же данных. Когда нужно работать с результатом, один decode с исключением даёт и проверку синтаксиса, и данные.

Упражнение: отправитель прислал readings как объект с ключами датчиков, хотя договор требует список. Где произошла ошибка? Правильный разбор: JSON синтаксически корректен, но схема изменилась. Уточните новую версию договора; не применяйте array_values без понимания, что означают ключи. Иначе можно отбросить именно идентификатор датчика.