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

От неоткрывающейся страницы к конкретному отказу

Покупатель выбрал CUP и LAMP, но страница каталога не открылась. Сообщения «что-то пошло не так» недостаточно разработчику; сырой ответ базы не подходит посетителю. В этой главе получим конкретный отказ, свяжем его с нужным запросом, исправим причину и покажем реальные товары. Затем разберём похожие ситуации, в которых CommandFailed вообще не появляется.

Предварительные шаги: товар, документ, коллекция и ограниченный запрос, начало и окончание команды, класс, объект и вызов метода. Здесь команда — документ с действием для сервера, например find для чтения или aggregate для отчёта. Событие — информация о конкретном этапе отправки/ответа. Подписчик — наш объект, метод которого драйвер вызывает при таком событии.

Минимальная прикладная задача — найти два артикула. PHP-список внутри $in содержит отдельные значения. Кавычки делают CUP строкой; запятая разделяет элементы массива; знак => связывает имя поля и его значение. Строка CUP,LAMP является одним значением и автоматически не делится.

$filter = ['sku' => ['$in' => ['CUP', 'LAMP']]];

Если драйвер вызвал commandFailed, параметр $event уже содержит объект события. Getter читает его значение: он не выполняет запрос заново. Переменная $name ниже получает имя реально отказавшей команды. Это короткая часть обработчика, а не отдельный исполняемый файл.

$name = $event->getCommandName(); // Например, find
$code = $event->getError()->getCode(); // Код наблюдаемого отказа

Метод commandFailed объявляется внутри класса, реализующего CommandSubscriber. Интерфейс задаёт три обязательных метода: commandStarted, commandSucceeded и commandFailed. У каждого есть параметр события, у результата тип void: метод сохраняет наблюдение и ничего не возвращает. Полный небольшой класс, регистрация в Manager и снятие в finally включены в helper каждого архива; вручную события не создаются.

Команда, соединение и результат записи — разные уровни

Мониторинг и результат операции отвечают на разные вопросы. Чтобы не путать их, сначала определим, дошло ли действие до выбранного сервера, затем прочитаем результат самой команды и результат записи/чтения.

Request ID связывает конкретные Started и Failed в контексте клиента. Operation ID группирует команды драйверной операции и не заменяет request ID: несколько команд могут разделять его, а значение "0" допустимо. Server connection ID относится к соединению и может отсутствовать; service ID относится к режиму load balancer и равен null на нашем Standalone. Ни одно из этих полей само по себе не является номером заказа.

GetError события возвращает Exception, но точный подкласс не обязан совпасть с исключением исходного вызова. На нашем стенде событие серверного отказа содержит ServerException, а executeReadCommand выбрасывает CommandException. Мы сохраняем класс и код каждого наблюдения, связываем события и не проверяем тождественность объектов. Полный errmsg и стек в публичную таблицу не копируются.

Времена сохраняются как фактические микросекунды. Они включают отправку команды и получение ответа; это не измерение всего HTTP-запроса и не обещание производительности. Callback не обращается к базе, не отправляет HTTP-запросы и не хранит объект исключения: он только добавляет разрешённые скалярные поля в ограниченный буфер. Ограничение в helper — 32 записи каждого вида, с отдельным счётчиком отброшенных.

Запустить текущие примеры и историческую миграцию

Для восьми текущих программ нужны PHP 8.4+ CLI x64, расширение mongodb 2.5+ и отдельный локальный MongoDB Community 8.0+. Проверяемая связка — PHP 8.5.11, mongodb 2.5.5, MongoDB 8.0.34. Composer не нужен. На сайте показаны сохранённые результаты; браузер посетителя не отправляет учебные ошибки в базу.

php --ri mongodb
$env:PHPMAN_MONGODB_URI='mongodb://127.0.0.1:27075/?directConnection=true&retryWrites=false'
$env:PHPMAN_MONGODB_DATABASE='php_manual_lab'
php example.php

Каждый ZIP распаковывается в свою папку вместе с mf124-helper.php и README.txt. README содержит установку подходящей DLL, проверку CLI php.ini, запуск mongod с отдельным dbpath и bind_ip=127.0.0.1. После запуска откройте result.html: там таблица и реальные обезличенные наблюдения. result.json содержит строки; metrics.json — фактические версии, проверки и хеши файлов.

Каждая программа создаёт ровно свою случайную коллекцию mongodb124_failures_… после проверки коллизии. Только успешный create даёт право на её удаление в finally; затем listCollections проверяет отсутствие. Никакие рабочие коллекции, серверные настройки или процессы не меняются. Для отказа соединения резервируется собственный порт без LISTEN; MongoDB не останавливается.

Исправить список артикулов: строка не является аргументом $in

Пользователь выбрал два товара, а вместо карточек сервис получил ошибку. Нужно увидеть, какая команда отказала, и исправить форму входных данных, сохранив полезный результат: CUP за 500 и LAMP за 1200.

Исходные данные и понятия

В учебной коллекции есть CUP, LAMP и архивный MAT. Неверный фильтр передаёт в $in строку CUP,LAMP. Правильный передаёт PHP-список из двух строк: при кодировании он становится массивом BSON. Название поля sku и оператор $in задаёт программа.

Короткая запись

$filter = ['sku' => ['$in' => ['CUP', 'LAMP']]];
// $in получает список значений; строка 'CUP,LAMP' сама в список не превращается.

Фрагмент выделяет текущее действие. Подготовка переменных, подписчик, собственные данные и очистка находятся в самостоятельной программе ниже.

Что получится

Как понимать результат

Квадратные скобки создают массив PHP; две строки через запятую — два элемента списка. MongoDB не разбирает запятые внутри одной строки как список. В журнале одно Started связано с одним Failed по requestId и контексту клиента. Новое успешное чтение имеет своё событие; ошибка не переписывается задним числом. Код 2 здесь наблюдается для конкретного BadValue, а не означает любую возможную ошибку фильтра.

Границы и типичные ошибки

Некоторые ошибки аргументов драйвер отклоняет ещё до отправки команды: там CommandFailed может не быть. Здесь намеренно выбран синтаксически кодируемый, но неправильный для сервера фильтр. GetError события и исключение catch не обязаны быть одним объектом или одним подклассом; проверяются реальный код и связь событий.

<?php
declare(strict_types=1);
require __DIR__.'/mf124-helper.php';
[$manager,$database,$runtime,$settings]=mf124Connect(false);
$owned=[];$journal=new Mf124Journal(false);$details=[];
try{
$collection=mf124Create($manager,$database,$owned);
$manager->addSubscriber($journal);
$failure=mf124Failure($manager,$database,['find'=>$collection,'filter'=>['sku'=>['$in'=>'CUP,LAMP']],'limit'=>2],$journal,2);
$products=mf124Screen($manager,$database,$collection,['sku'=>['$in'=>['CUP','LAMP']]]);
$rows=[['Ошибка фильтра',$failure['event']['command'],$failure['event']['error_code']]];
foreach($products as $product){$rows[]=['Полученный товар',$product['sku'],$product['price']];}
$checks=['failure_request_paired'=>$failure['paired'],'corrected_products'=>$products===[['sku'=>'CUP','price'=>500],['sku'=>'LAMP','price'=>1200]],
    'failed_then_success'=>count($journal->failed)===1 && count($journal->succeeded)===1];
$details=['Исключение вызывающего кода'=>$failure['caught'],'Смысл'=>'CommandFailed связан со своим Started; исправленный find — новая команда'];
}finally{
    $manager->removeSubscriber($journal);
    foreach(array_reverse($owned) as $name){mf124Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(mf124Exists($manager,$database,$name)){$removed=false;}}
$checks['owned_collection_removed']=$removed;
$checks['journal_types_and_endpoint']=mf124JournalValid($journal,$settings,$database);
$details['started']=array_values($journal->started);$details['failed']=array_values($journal->failed);
$details['succeeded']=array_values($journal->succeeded);$details['expected_deprecations']=$journal->deprecations;
$checks['expected_rows']=$rows===[['Ошибка фильтра', 'find', 2], ['Полученный товар', 'CUP', 500], ['Полученный товар', 'LAMP', 1200]];
mf124Report('mongodb124-failures-invalid-filter',['Результат', 'Команда / артикул', 'Код / цена'],$rows,$checks,$runtime,$details);
echo 'mongodb124-failures-invalid-filter: OK',"\n";

mongodb124-failures-invalid-filter: OK

Открыть настоящую таблицу и наблюдения · Строки результата JSON

Упражнение с направлением решения. Нужно получить только LAMP. Передайте список ['LAMP']; ожидается одна карточка с ценой 1200. Не подменяйте ошибку сервера пустым массивом: иначе пользователь не отличит поломанный поиск от отсутствия товаров.

Вопрос из практики: Doctrine MongoDb — ReferenceMany loading says Cannot canonicalize query. При загрузке связанных данных разработчик получил $in needs an array. Старая ODM-среда не переносится в урок: используем отдельный текущий пример с явным неправильным значением и исправленным списком. Обсуждение использовано для постановки задачи, не как источник современного API; решения и данные этой главы составлены отдельно.

Найти опечатку этапа отчёта и получить итог активного каталога

Отчёт по активному каталогу перестал открываться после изменения этапов агрегации. Покажем отказ неизвестного этапа и исправленный результат: два товара с суммой цен 1700.

Исходные данные и понятия

Pipeline — упорядоченный список этапов обработки документов. Каждый элемент здесь является документом с именем этапа. Неверное имя $aenMissingStage124 нужно только для воспроизведения отказа. В исправлении $match оставляет active, $group считает товары и сумму, $project выбирает поля результата.

Короткая запись

$pipeline = [
    ['$match' => ['status' => 'active']],
    ['$group' => ['_id' => null, 'products' => ['$sum' => 1]]],
]; // Имена этапов задаёт программа; неизвестный $aenMissingStage124 сервер отклонит.

Фрагмент выделяет текущее действие. Подготовка переменных, подписчик, собственные данные и очистка находятся в самостоятельной программе ниже.

Что получится

Как понимать результат

CommandFailed сообщает уровень команды: сервер не выполнил такую pipeline. После исправления возвращается один документ отчёта, а не весь каталог для подсчёта в PHP. $sum: 1 увеличивает счётчик на каждый подходящий документ; $sum: $price складывает цены. Отсутствующий _id в выводе задаётся проекцией, это не изменение исходных товаров. Первая партия задана batchSize=2: единственный итог помещается в неё, поэтому здесь проверяются ровно два aggregate — отказавший и исправленный. При batchSize=1 первая партия заполнялась целиком и для завершения чтения драйвер выполнял дополнительный getMore. Размер партии не является общим лимитом отчёта.

Границы и типичные ошибки

40324 — код неизвестного этапа на используемом MongoDB 8.0. Другие ошибки агрегации имеют другие коды. Названия этапов и выражения нельзя брать из произвольного пользовательского JSON без собственного контракта. Успешность на трёх товарах не является измерением стоимости большого отчёта.

<?php
declare(strict_types=1);
require __DIR__.'/mf124-helper.php';
[$manager,$database,$runtime,$settings]=mf124Connect(false);
$owned=[];$journal=new Mf124Journal(false);$details=[];
try{
$collection=mf124Create($manager,$database,$owned);
$manager->addSubscriber($journal);
$failure=mf124Failure($manager,$database,['aggregate'=>$collection,'pipeline'=>[['$aenMissingStage124'=>new stdClass]],'cursor'=>new stdClass],$journal,40324);
$summary=mf124Command($manager,$database,['aggregate'=>$collection,'pipeline'=>[
    ['$match'=>['status'=>'active']],['$group'=>['_id'=>null,'products'=>['$sum'=>1],'total'=>['$sum'=>'$price']]],
    ['$project'=>['_id'=>0,'products'=>1,'total'=>1]]],'cursor'=>['batchSize'=>2],'maxTimeMS'=>2000]);
$rows=[['Ошибка этапа',$failure['event']['command'],$failure['event']['error_code']],
    ['Исправленный отчёт','активных товаров',$summary[0]['products']],['Исправленный отчёт','сумма цен',$summary[0]['total']]];
$checks=['actual_pipeline_failure'=>$failure['paired'],'actual_report'=>$summary===[['products'=>2,'total'=>1700]],
    'distinct_requests'=>array_column($journal->started,'command')===['aggregate','aggregate']
        && array_column($journal->failed,'command')===['aggregate'] && array_column($journal->succeeded,'command')===['aggregate']];
$details=['Отказ'=>$failure['caught'],'Результат отчёта'=>$summary];
}finally{
    $manager->removeSubscriber($journal);
    foreach(array_reverse($owned) as $name){mf124Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(mf124Exists($manager,$database,$name)){$removed=false;}}
$checks['owned_collection_removed']=$removed;
$checks['journal_types_and_endpoint']=mf124JournalValid($journal,$settings,$database);
$details['started']=array_values($journal->started);$details['failed']=array_values($journal->failed);
$details['succeeded']=array_values($journal->succeeded);$details['expected_deprecations']=$journal->deprecations;
$checks['expected_rows']=$rows===[['Ошибка этапа', 'aggregate', 40324], ['Исправленный отчёт', 'активных товаров', 2], ['Исправленный отчёт', 'сумма цен', 1700]];
mf124Report('mongodb124-failures-invalid-pipeline',['Наблюдение', 'Команда / показатель', 'Код / результат'],$rows,$checks,$runtime,$details);
echo 'mongodb124-failures-invalid-pipeline: OK',"\n";

mongodb124-failures-invalid-pipeline: OK

Открыть настоящую таблицу и наблюдения · Строки результата JSON

Упражнение с направлением решения. Нужен только счётчик, без суммы. Уберите total из $group и итоговой проекции; результат должен остаться products=2. Это сокращает контракт ответа, а не требует сначала загрузить все товары.

Отличить ошибочный hint от пустого результата поиска

После переноса сервиса запрос с жёстко заданным именем индекса отказал. Разберём, почему это не пустой каталог, и получим корректный экран с нужными полями.

Исходные данные и понятия

В новой собственной коллекции нет индекса aen_missing_price_index124. Запрос принудительно указывает его в hint и получает серверный отказ. Затем выполняется такой же полезный фильтр active без этого ошибочного указания, с сортировкой price/sku и limit=2.

Короткая запись

$command = ['find' => $collection, 'filter' => ['status' => 'active'],
    'projection' => ['_id' => 0, 'sku' => 1, 'price' => 1], 'limit' => 2];
// hint отсутствующего индекса не является просьбой «использовать индекс, если он есть».

Фрагмент выделяет текущее действие. Подготовка переменных, подписчик, собственные данные и очистка находятся в самостоятельной программе ниже.

Что получится

Как понимать результат

Hint задаёт выбор индекса; это не необязательная подсказка «если найдётся». В примере отказ имеет код 2. Исправленный запрос возвращает две реальные строки. Ни код ошибки, ни число CommandFailed не подменяют сам список товаров: он показан отдельно. Для рабочего релиза нужно выяснить причину отсутствия индекса и согласовать миграцию схемы/запроса.

Границы и типичные ошибки

Автоматически снимать hint при любой ошибке нельзя: он может быть частью осознанного эксплуатационного контракта. Здесь снятие явно написано как учебное исправление, а не скрытый retry. Никакого обещания о выборе индекса, отсутствии сортировки или ускорении этот запуск не делает.

<?php
declare(strict_types=1);
require __DIR__.'/mf124-helper.php';
[$manager,$database,$runtime,$settings]=mf124Connect(false);
$owned=[];$journal=new Mf124Journal(false);$details=[];
try{
$collection=mf124Create($manager,$database,$owned);
$manager->addSubscriber($journal);
$failure=mf124Failure($manager,$database,['find'=>$collection,'filter'=>['status'=>'active'],
    'hint'=>'aen_missing_price_index124','limit'=>2,'maxTimeMS'=>2000],$journal,2);
$products=mf124Screen($manager,$database,$collection,['status'=>'active']);
$rows=[['find с отсутствующим индексом',$failure['event']['error_code'],'отказ команды'],
    ['Запрос без этого hint',count($products),implode(', ',array_column($products,'sku'))]];
$checks=['real_bad_hint'=>$failure['paired'],'actual_bounded_screen'=>$products===[['sku'=>'CUP','price'=>500],['sku'=>'LAMP','price'=>1200]],
    'failure_not_empty_result'=>count($journal->failed)===1 && count($products)===2];
$details=['Ошибка'=>$failure['caught'],'После исправления'=>$products,
    'Граница'=>'Снятие ошибочного hint исправляет этот запрос; эффективность плана здесь не измеряется'];
}finally{
    $manager->removeSubscriber($journal);
    foreach(array_reverse($owned) as $name){mf124Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(mf124Exists($manager,$database,$name)){$removed=false;}}
$checks['owned_collection_removed']=$removed;
$checks['journal_types_and_endpoint']=mf124JournalValid($journal,$settings,$database);
$details['started']=array_values($journal->started);$details['failed']=array_values($journal->failed);
$details['succeeded']=array_values($journal->succeeded);$details['expected_deprecations']=$journal->deprecations;
$checks['expected_rows']=$rows===[['find с отсутствующим индексом', 2, 'отказ команды'], ['Запрос без этого hint', 2, 'CUP, LAMP']];
mf124Report('mongodb124-failures-missing-hint',['Запрос', 'Код / количество', 'Что увидели'],$rows,$checks,$runtime,$details);
echo 'mongodb124-failures-missing-hint: OK',"\n";

mongodb124-failures-missing-hint: OK

Открыть настоящую таблицу и наблюдения · Строки результата JSON

Упражнение с направлением решения. На стенде появился нужный индекс с другим именем. Сначала сверяйте listIndexes и соответствие запросу; затем меняйте конфигурацию. Не преобразуйте исключение в «найдено 0 товаров». Подробнее устройство индексов разобрано в связанной главе.

Вопрос из практики: MongoDB indexes unexpectedly getting removed; hint fails. Запрос с hint отказал при отсутствии ожидаемого индекса. Не принимаем предположение об автоматическом удалении как установленный факт; показываем диагностируемый отказ и явное исправление собственной тестовой команды. Обсуждение использовано для постановки задачи, не как источник современного API; решения и данные этой главы составлены отдельно.

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

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

Исходные данные и понятия

Документ команды начинается с aenManualUnknown124: 1. Такой команды нет. После его отказа программа отправляет штатный ping и получает ok=1. Данные коллекции не меняются.

Короткая запись

$reply = $manager->executeReadCommand($database,
    new MongoDB\Driver\Command(['ping' => 1]));
// Имя команды — ключ первого поля документа; произвольное имя сервер не исполнит.

Фрагмент выделяет текущее действие. Подготовка переменных, подписчик, собственные данные и очистка находятся в самостоятельной программе ниже.

Что получится

Как понимать результат

Имя команды находится в первом поле её BSON-документа. 59 обозначает CommandNotFound на данном сервере. Наличие такого ответа уже отличается от невозможности найти сервер: ответ пришёл по сети. Успешный ping подтверждает только эту проверку, а не права пользователя на все коллекции или корректность любого последующего запроса.

Границы и типичные ошибки

Не используйте произвольный список неизвестных команд для разведки производственного сервера. Здесь одна заранее известная учебная ошибка. В журнале сохраняется codeName, когда сервер его прислал; этот необязательный текст не используется вместо числового кода и реального исключения.

<?php
declare(strict_types=1);
require __DIR__.'/mf124-helper.php';
[$manager,$database,$runtime,$settings]=mf124Connect(false);
$owned=[];$journal=new Mf124Journal(false);$details=[];
try{
$collection=mf124Create($manager,$database,$owned);
$manager->addSubscriber($journal);
$failure=mf124Failure($manager,$database,['aenManualUnknown124'=>1],$journal,59);
$reply=mf124Command($manager,$database,['ping'=>1]);
$rows=[['Неподдерживаемая команда',$failure['event']['command'],$failure['event']['error_code']],
    ['Исправленная проверка','ping',(int)$reply[0]['ok']]];
$checks=['real_unknown_command'=>$failure['paired'],'server_answered_ping'=>(float)$reply[0]['ok']===1.0,
    'two_distinct_outcomes'=>count($journal->failed)===1 && count($journal->succeeded)===1];
$details=['Исключение операции'=>$failure['caught'],'Причина'=>'Сервер ответил кодом 59; это не доказательство сетевого отказа'];
}finally{
    $manager->removeSubscriber($journal);
    foreach(array_reverse($owned) as $name){mf124Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(mf124Exists($manager,$database,$name)){$removed=false;}}
$checks['owned_collection_removed']=$removed;
$checks['journal_types_and_endpoint']=mf124JournalValid($journal,$settings,$database);
$details['started']=array_values($journal->started);$details['failed']=array_values($journal->failed);
$details['succeeded']=array_values($journal->succeeded);$details['expected_deprecations']=$journal->deprecations;
$checks['expected_rows']=$rows===[['Неподдерживаемая команда', 'aenManualUnknown124', 59], ['Исправленная проверка', 'ping', 1]];
mf124Report('mongodb124-failures-unknown-command',['Проверка', 'Команда', 'Код / ok'],$rows,$checks,$runtime,$details);
echo 'mongodb124-failures-unknown-command: OK',"\n";

mongodb124-failures-unknown-command: OK

Открыть настоящую таблицу и наблюдения · Строки результата JSON

Упражнение с направлением решения. Какая надпись точнее: «сервер не отвечает» или «сервер отклонил неизвестную команду»? В этом опыте верна вторая. Первая требует самостоятельных сведений об ошибке соединения.

Не считать отсутствие CommandFailed успешным подключением

Счётчик CommandFailed равен нулю, но клиент не смог получить даже ping. Покажем отсутствие события как ограничение наблюдения, затем отдельно прочитаем товары с здорового стенда.

Исходные данные и понятия

Программа занимает свой случайный loopback-порт без слушателя. Для отдельного Manager подбор ограничен serverSelectionTimeoutMS=500, соединение connectTimeoutMS=300. Это не сервер MongoDB. Исходный настоящий mongod не останавливается.

Короткая запись

try {
    $manager->executeReadCommand($database, new MongoDB\Driver\Command(['ping' => 1]));
} catch (MongoDB\Driver\Exception\ConnectionException $error) {
    $status = 'Не удалось соединиться'; // Отдельно от счётчика CommandFailed.
}

Фрагмент выделяет текущее действие. Подготовка переменных, подписчик, собственные данные и очистка находятся в самостоятельной программе ниже.

Что получится

Как понимать результат

CommandSubscriber наблюдает прикладные команды. Если до выбора подходящего сервера дело не дошло, отправленной команды и её пары Started/Failed нет. Служебный heartbeat относится к другому интерфейсу SDAMSubscriber. Catch операции поэтому обязателен независимо от журнала. Вторая строка — отдельное чтение с известного стенда, а не автоматическое восстановление первого endpoint.

Границы и типичные ошибки

500 мс ограничивает соответствующую стадию драйвера, а не обещает точное внешнее время процесса. Нельзя делать вывод «все сетевые ошибки не дают CommandFailed»: отказ после начала команды — другой случай. Нельзя автоматически переносить запись на другую базу после неопределённого исхода.

<?php
declare(strict_types=1);
require __DIR__.'/mf124-helper.php';
[$manager,$database,$runtime,$settings]=mf124Connect(false);
$owned=[];$journal=new Mf124Journal(false);$details=[];
try{
$collection=mf124Create($manager,$database,$owned);
$manager->addSubscriber($journal);
$manager->removeSubscriber($journal);$bad=null;$socket=null;$connectionError=null;
[$socket,$failureUri]=mf124BoundEndpoint();
try{
    $bad=mf124Manager($failureUri,true);$bad->addSubscriber($journal);
    try{mf124Command($bad,$database,['ping'=>1]);}
    catch(MongoDB\Driver\Exception\ConnectionException $error){$connectionError=get_class($error);unset($error);}
    $before=['started'=>count($journal->started),'failed'=>count($journal->failed),'succeeded'=>count($journal->succeeded)];
}finally{
    if($bad!==null){$bad->removeSubscriber($journal);}unset($bad);
    if(is_resource($socket)){fclose($socket);}
}
$manager->addSubscriber($journal);
$products=mf124Screen($manager,$database,$collection,['status'=>'active']);
$rows=[['Подбор недоступного сервера',$connectionError!==null?'ошибка соединения':'нет ошибки',$before['started'],$before['failed']],
    ['Чтение с известного стенда',implode(', ',array_column($products,'sku')),count($journal->started),count($journal->failed)]];
$checks=['actual_selection_error'=>$connectionError!==null,'no_command_sent'=>$before===['started'=>0,'failed'=>0,'succeeded'=>0],
    'healthy_result'=>$products===[['sku'=>'CUP','price'=>500],['sku'=>'LAMP','price'=>1200]],'healthy_success_recorded'=>count($journal->succeeded)===1];
$details=['Класс отказа до команды'=>$connectionError,'Отказавший endpoint'=>$failureUri,
    'Граница'=>'Не было выбранного MongoDB-сервера и отправленной прикладной команды. Heartbeat относится к SDAM, а не этому CommandSubscriber'];
}finally{
    $manager->removeSubscriber($journal);
    foreach(array_reverse($owned) as $name){mf124Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(mf124Exists($manager,$database,$name)){$removed=false;}}
$checks['owned_collection_removed']=$removed;
$checks['journal_types_and_endpoint']=mf124JournalValid($journal,$settings,$database);
$details['started']=array_values($journal->started);$details['failed']=array_values($journal->failed);
$details['succeeded']=array_values($journal->succeeded);$details['expected_deprecations']=$journal->deprecations;
$checks['expected_rows']=$rows===[['Подбор недоступного сервера', 'ошибка соединения', 0, 0], ['Чтение с известного стенда', 'CUP, LAMP', 1, 0]];
mf124Report('mongodb124-failures-connection-selection',['Действие', 'Фактический итог', 'CommandStarted', 'CommandFailed'],$rows,$checks,$runtime,$details);
echo 'mongodb124-failures-connection-selection: OK',"\n";

mongodb124-failures-connection-selection: OK

Открыть настоящую таблицу и наблюдения · Строки результата JSON

Упражнение с направлением решения. В панели ноль событий и одновременно ConnectionTimeoutException. Покажите отдельный статус «соединение не установлено», а не зелёный статус из отсутствия ошибок команд. Для исследования hello используйте журнал SDAM.

Не принять CommandSucceeded за успешную вставку товара

Импорт показал зелёное событие CommandSucceeded, но новая запись не появилась. Разделим три уровня: MongoDB ответила на insert, одна вставка получила writeErrors, приложение получило BulkWriteException.

Исходные данные и понятия

У товара CUP уже есть _id=1 и цена 500. Пример пытается вставить другую запись с тем же _id. Уникальный индекс _id существует автоматически. После отказа исходный CUP читается отдельным ограниченным запросом.

Короткая запись

catch (MongoDB\Driver\Exception\BulkWriteException $error) {
    $result = $error->getWriteResult();
    $errors = $result->getWriteErrors();
} // Даже если мониторинг сообщил CommandSucceeded, результат записи проверяется отдельно.

Фрагмент выделяет текущее действие. Подготовка переменных, подписчик, собственные данные и очистка находятся в самостоятельной программе ниже.

Что получится

Как понимать результат

На уровне протокола команда ответила успешно; ошибка конкретной записи находится внутри ответа. Поэтому CommandFailed здесь равен нулю. Программа проверяет writeErrors, отсутствие отдельной writeConcernError и количество реально вставленных документов. Само слово Succeeded не является квитанцией «товар сохранён».

Границы и типичные ошибки

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

<?php
declare(strict_types=1);
require __DIR__.'/mf124-helper.php';
[$manager,$database,$runtime,$settings]=mf124Connect(false);
$owned=[];$journal=new Mf124Journal(false);$details=[];
try{
$collection=mf124Create($manager,$database,$owned);
$manager->addSubscriber($journal);
$bulk=new MongoDB\Driver\BulkWrite;$bulk->insert(['_id'=>1,'sku'=>'DUPLICATE','price'=>999]);$caught=null;$writeResult=null;
try{$manager->executeBulkWrite($database.'.'.$collection,$bulk,['writeConcern'=>new MongoDB\Driver\WriteConcern(1,2000)]);}
catch(MongoDB\Driver\Exception\BulkWriteException $error){
    $writeResult=$error->getWriteResult();$errors=$writeResult->getWriteErrors();
    if(count($errors)!==1 || $errors[0]->getCode()!==11000 || $writeResult->getWriteConcernError()!==null){throw $error;}
    $caught=['class'=>get_class($error),'code'=>$errors[0]->getCode()];unset($error);
}
if($caught===null){throw new RuntimeException('Expected duplicate _id');}
$insert=null;foreach($journal->succeeded as $event){if($event['command']==='insert'){$insert=$event;break;}}
if($insert===null){throw new RuntimeException('Actual CommandSucceeded insert was not observed');}
$original=mf124Screen($manager,$database,$collection,['sku'=>'CUP']);
$rows=[['Событие команды','CommandSucceeded',(int)$insert['reply']['ok']],
    ['Результат записи','дубликат _id',$caught['code']],['Вставлено документов','insertedCount',$writeResult->getInsertedCount()],
    ['Исходный товар',$original[0]['sku'],$original[0]['price']]];
$checks=['write_error_in_success_reply'=>$insert['write_error_codes']===[11000],
    'no_failed_command'=>count($journal->failed)===0,'no_inserted_duplicate'=>$writeResult->getInsertedCount()===0,
    'original_unchanged'=>$original===[['sku'=>'CUP','price'=>500]],
    'insert_request_paired'=>isset($journal->started[$insert['request_id']])];
$details=['Исключение записи'=>$caught,'Полученный исходный товар'=>$original,
    'Разделение'=>'Команда insert получила ответ ok=1; отказ одной записи находится в writeErrors и WriteResult'];
}finally{
    $manager->removeSubscriber($journal);
    foreach(array_reverse($owned) as $name){mf124Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(mf124Exists($manager,$database,$name)){$removed=false;}}
$checks['owned_collection_removed']=$removed;
$checks['journal_types_and_endpoint']=mf124JournalValid($journal,$settings,$database);
$details['started']=array_values($journal->started);$details['failed']=array_values($journal->failed);
$details['succeeded']=array_values($journal->succeeded);$details['expected_deprecations']=$journal->deprecations;
$checks['expected_rows']=$rows===[['Событие команды', 'CommandSucceeded', 1], ['Результат записи', 'дубликат _id', 11000], ['Вставлено документов', 'insertedCount', 0], ['Исходный товар', 'CUP', 500]];
mf124Report('mongodb124-failures-write-errors-success',['Уровень', 'Наблюдение', 'Значение'],$rows,$checks,$runtime,$details);
echo 'mongodb124-failures-write-errors-success: OK',"\n";

mongodb124-failures-write-errors-success: OK

Открыть настоящую таблицу и наблюдения · Строки результата JSON

Упражнение с направлением решения. Что показывать пользователю импорта? «Запись с таким ID уже существует; добавлено 0». Для операторского журнала рядом оставить CommandSucceeded с writeErrors. Эти сообщения дополняют друг друга, а не противоречат.

Собрать две понятные диагностические записи без данных покупателя

Разработчику нужны подробности двух отказов — экрана каталога и отчёта остатков, — но в обращение в поддержку не должны попасть значения покупателя и полный документ запроса.

Исходные данные и понятия

Две реальные ошибочные команды содержат учебный private-customer@example.invalid. Callback получает событие, но сохраняет лишь разрешённые поля: имя команды, базу, endpoint, requestId/operationId, длительность, тип/код ошибки и ok/code/codeName из ответа. Прикладная метка действия добавляется отдельно.

Короткая запись

$reply = $event->getReply();
$record = ['command' => $event->getCommandName(), 'code' => $reply->code ?? null,
    'request_id' => $event->getRequestId()];
// Не добавляем весь reply/errmsg: текст ошибки может содержать значения запроса.

Фрагмент выделяет текущее действие. Подготовка переменных, подписчик, собственные данные и очистка находятся в самостоятельной программе ниже.

Что получится

Как понимать результат

Allowlist — явный перечень разрешённых полей. Он устойчивее, чем попытка удалить одно известное поле из целого сырого ответа: завтра сервер может добавить другие подробности. В таблице serviceId отсутствует, потому что стенд прямой, без load balancer. Реальные connectionId и длительности остаются в подробностях, а не подставляются константами.

Границы и типичные ошибки

Даже имя базы, адрес узла и служебные ID являются эксплуатационными данными; в публичном сервисе доступ к ним тоже ограничивают. Эта небольшая политика не заменяет аудит конфиденциальности всей системы. Отсутствующий serviceId нельзя заменять придуманным ObjectId или трактовать как отказ.

<?php
declare(strict_types=1);
require __DIR__.'/mf124-helper.php';
[$manager,$database,$runtime,$settings]=mf124Connect(false);
$owned=[];$journal=new Mf124Journal(false);$details=[];
try{
$collection=mf124Create($manager,$database,$owned);
$manager->addSubscriber($journal);
$secret='private-customer@example.invalid';
$one=mf124Failure($manager,$database,['find'=>$collection,'filter'=>['sku'=>['$in'=>$secret]],'limit'=>2],$journal,2);
$two=mf124Failure($manager,$database,['aggregate'=>$collection,'pipeline'=>[['$aenMissingStage124'=>['private_note'=>$secret]]],'cursor'=>new stdClass],$journal,40324);
$rows=[];$sanitized=[];
foreach([['экран каталога',$one],['отчёт остатков',$two]] as [$label,$failure]){
    $event=$failure['event'];$sanitized[]=['action'=>$label]+$event;
    $rows[]=[$label,$event['command'],$event['error_code'],$failure['paired'],$event['service_id']===null];
}
$encoded=json_encode($sanitized,JSON_THROW_ON_ERROR);
$checks=['both_real_failures'=>count($journal->failed)===2,'private_value_excluded'=>!str_contains($encoded,$secret),
    'unapproved_reply_excluded'=>!str_contains($encoded,'errmsg') && !str_contains($encoded,'private_note'),
    'requests_distinct'=>$one['event']['request_id']!==$two['event']['request_id']];
$details=['Диагностические записи с назначением'=>$sanitized,
    'Порядок'=>'action задана приложением; IDs и code берутся из реального события. Имя базы/endpoint тоже требуют контроля доступа к журналу'];
}finally{
    $manager->removeSubscriber($journal);
    foreach(array_reverse($owned) as $name){mf124Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(mf124Exists($manager,$database,$name)){$removed=false;}}
$checks['owned_collection_removed']=$removed;
$checks['journal_types_and_endpoint']=mf124JournalValid($journal,$settings,$database);
$details['started']=array_values($journal->started);$details['failed']=array_values($journal->failed);
$details['succeeded']=array_values($journal->succeeded);$details['expected_deprecations']=$journal->deprecations;
$checks['expected_rows']=$rows===[['экран каталога', 'find', 2, true, true], ['отчёт остатков', 'aggregate', 40324, true, true]];
mf124Report('mongodb124-failures-incident-report',['Действие', 'Команда', 'Код', 'Started найден', 'serviceId отсутствует'],$rows,$checks,$runtime,$details);
echo 'mongodb124-failures-incident-report: OK',"\n";

mongodb124-failures-incident-report: OK

Открыть настоящую таблицу и наблюдения · Строки результата JSON

Упражнение с направлением решения. Нужен номер действия пользователя. Добавьте собственный applicationRequestId, не используя requestId драйвера как идентификатор заказа. Сопоставление команд по driver requestId оставьте внутри контекста клиента/запуска.

Превратить вход формы в ограниченный запрос и различить пустой список

Форма присылает строку с выбранными артикулами. Построим путь до реального экрана: разбить строку, проверить значения, отправить ограниченный запрос, а также честно определить поведение пустого выбора.

Исходные данные и понятия

Исходная строка — пробел, CUP, запятая, пробел, LAMP. explode делит по запятой, trim удаляет крайние пробелы, array_filter убирает пустые элементы, array_unique исключает повторы, array_values восстанавливает последовательные индексы списка. Допускаются не более десяти артикулов из известного набора.

Короткая запись

$input = ' CUP, LAMP ';
$skus = array_map('trim', explode(',', $input)); // ['CUP', 'LAMP']
$filter = ['status' => 'active', 'sku' => ['$in' => $skus]];
// Полная программа проверяет допустимые SKU/количество, задаёт projection, sort, limit.

Фрагмент выделяет текущее действие. Подготовка переменных, подписчик, собственные данные и очистка находятся в самостоятельной программе ниже.

Что получится

Как понимать результат

Фильтрация, порядок и предел результата заданы MongoDB до переноса данных в PHP. Пустой массив $in корректен, но не содержит ни одного допустимого значения, поэтому не означает «любой товар». Если по правилам интерфейса отсутствие выбора должно означать все активные товары, программа должна осознанно убрать условие sku, сохранив limit и другие ограничения.

Границы и типичные ошибки

Это короткий учебный список, не универсальный парсер пользовательских условий. Если значение sku может содержать запятую, нужен другой формат входа. Внешние $-ключи не становятся операторами запроса. Полноценная форма требует собственной валидации, статусов HTTP и безопасного вывода, которые изучаются отдельно.

<?php
declare(strict_types=1);
require __DIR__.'/mf124-helper.php';
[$manager,$database,$runtime,$settings]=mf124Connect(false);
$owned=[];$journal=new Mf124Journal(false);$details=[];
try{
$collection=mf124Create($manager,$database,$owned);
$manager->addSubscriber($journal);
$input=' CUP, LAMP ';
$failure=mf124Failure($manager,$database,['find'=>$collection,'filter'=>['sku'=>['$in'=>$input]],'limit'=>2],$journal,2);
$skus=array_values(array_unique(array_filter(array_map('trim',explode(',',$input)),fn($v)=>$v!=='')));
if(count($skus)>10 || array_filter($skus,fn($v)=>!in_array($v,['CUP','LAMP','MAT'],true))){throw new InvalidArgumentException('Invalid SKU selection');}
$products=mf124Screen($manager,$database,$collection,['status'=>'active','sku'=>['$in'=>$skus]]);
$empty=mf124Screen($manager,$database,$collection,['status'=>'active','sku'=>['$in'=>[]]]);
$rows=[['До преобразования','ошибка find',$failure['event']['error_code']]];
foreach($products as $product){$rows[]=['После проверки списка',$product['sku'],$product['price']];}
$rows[]=['Пустой список $in','совпадений',count($empty)];
$checks=['actual_initial_error'=>$failure['paired'],'normalized_list'=>$skus===['CUP','LAMP'],
    'projected_limited_result'=>$products===[['sku'=>'CUP','price'=>500],['sku'=>'LAMP','price'=>1200]],
    'empty_is_no_matches'=>$empty===[],'one_error_two_successes'=>count($journal->failed)===1 && count($journal->succeeded)===2];
$details=['Нормализованные артикулы'=>$skus,'Реальная выборка'=>$products,'Пустой список'=>$empty,
    'Граница'=>'Условия и операторы создаёт программа. Пользовательские массивы с $-ключами не передаются в запрос как готовый фильтр'];
}finally{
    $manager->removeSubscriber($journal);
    foreach(array_reverse($owned) as $name){mf124Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(mf124Exists($manager,$database,$name)){$removed=false;}}
$checks['owned_collection_removed']=$removed;
$checks['journal_types_and_endpoint']=mf124JournalValid($journal,$settings,$database);
$details['started']=array_values($journal->started);$details['failed']=array_values($journal->failed);
$details['succeeded']=array_values($journal->succeeded);$details['expected_deprecations']=$journal->deprecations;
$checks['expected_rows']=$rows===[['До преобразования', 'ошибка find', 2], ['После проверки списка', 'CUP', 500], ['После проверки списка', 'LAMP', 1200], ['Пустой список $in', 'совпадений', 0]];
mf124Report('mongodb124-failures-corrected-screen',['Этап', 'Итог', 'Код / цена / количество'],$rows,$checks,$runtime,$details);
echo 'mongodb124-failures-corrected-screen: OK',"\n";

mongodb124-failures-corrected-screen: OK

Открыть настоящую таблицу и наблюдения · Строки результата JSON

Упражнение с направлением решения. Пустой выбор должен показывать первые два активных товара. После нормализации сформируйте базовый фильтр status=active и добавляйте sku/$in только для непустого списка. Не убирайте limit вместе с условием.

Вопрос из практики: $in operator and an empty list. Разработчик смешал отсутствующее значение, пустой список и желание показать все документы. Урок на PHP различает неправильную строку, проверенный список и корректный пустой $in без совпадений. Обсуждение использовано для постановки задачи, не как источник современного API; решения и данные этой главы составлены отдельно.

Перенести два старых отчёта об ошибке с getServer на host и port

В старом обработчике отказов адрес сервера получался через getServer. После перехода на расширение 2.x этот метод удалён. Воспроизведём два старых случая и проверим, что прямые getHost/getPort дают тот же endpoint.

Исходные данные и понятия

Изолированный PHP 8.4.27 с mongodb 1.20.1 подключается к тому же локальному MongoDB 8.0.34. Ошибки find и aggregate настоящие. Только в их callbacks вызывается getServer и записывается ожидаемое предупреждение E_DEPRECATED.

Короткая запись

// Только ext-mongodb 1.20: этот вызов deprecated.
$server = $event->getServer();
$oldAddress = [$server->getHost(), $server->getPort()];
// С 1.20 доступна замена; на 2.x используйте только её:
$address = [$event->getHost(), $event->getPort()];

Фрагмент выделяет текущее действие. Подготовка переменных, подписчик, собственные данные и очистка находятся в самостоятельной программе ниже.

Что получится

Как понимать результат

Начиная с mongodb 1.20 getHost/getPort позволяют взять адрес без отдельного Server. getServer тогда уже deprecated; в 2.0 он удалён. Две строки результата соответствуют двум реальным применениям старого обработчика, а не имитации метода на новой версии. Обработчик предупреждения принимает ровно известный E_DEPRECATED и не скрывает остальные проблемы.

Границы и типичные ошибки

Не устанавливайте старую DLL поверх рабочего PHP ради этой главы. Старый отдельный runtime нужен только для миграционного опыта. Server из события может удерживать внутренний клиент; здесь сохраняется адрес, а объект освобождается. Повторный вызов MongoDB из callback не нужен.

<?php
declare(strict_types=1);
require __DIR__.'/mf124-helper.php';
[$manager,$database,$runtime,$settings]=mf124Connect(true);
$owned=[];$journal=new Mf124Journal(true);$details=[];
try{
$collection=mf124Create($manager,$database,$owned);
$manager->addSubscriber($journal);
$one=mf124Failure($manager,$database,['find'=>$collection,'filter'=>['sku'=>['$in'=>'CUP']],'limit'=>1],$journal,2);
$two=mf124Failure($manager,$database,['aggregate'=>$collection,'pipeline'=>[['$aenMissingStage124'=>new stdClass]],'cursor'=>new stdClass],$journal,40324);
$rows=[];
foreach([$one,$two] as $failure){
    $event=$failure['event'];$same=$event['legacy_endpoint']===[$event['host'],$event['port']];
    $rows[]=[$event['command'],$event['error_code'],$same,'getHost() + getPort()'];
}
$checks=['two_real_failures'=>count($journal->failed)===2,'two_expected_deprecations'=>count($journal->deprecations)===2,
    'legacy_matches_current'=>$rows[0][2] && $rows[1][2],
    'legacy_method_exists'=>method_exists(MongoDB\Driver\Monitoring\CommandFailedEvent::class,'getServer')];
$details=['Предупреждения'=>$journal->deprecations,'Миграция'=>'Старая версия нужна только для воспроизведения; основной код не требует Server из события'];
}finally{
    $manager->removeSubscriber($journal);
    foreach(array_reverse($owned) as $name){mf124Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(mf124Exists($manager,$database,$name)){$removed=false;}}
$checks['owned_collection_removed']=$removed;
$checks['journal_types_and_endpoint']=mf124JournalValid($journal,$settings,$database);
$details['started']=array_values($journal->started);$details['failed']=array_values($journal->failed);
$details['succeeded']=array_values($journal->succeeded);$details['expected_deprecations']=$journal->deprecations;
$checks['expected_rows']=$rows===[['find', 2, true, 'getHost() + getPort()'], ['aggregate', 40324, true, 'getHost() + getPort()']];
mf124Report('mongodb124-failures-server-legacy',['Старая диагностика', 'Код отказа', 'Endpoint совпал', 'Современная замена'],$rows,$checks,$runtime,$details);
echo 'mongodb124-failures-server-legacy: OK',"\n";

mongodb124-failures-server-legacy: OK

Открыть настоящую таблицу и наблюдения · Строки результата JSON

Упражнение с направлением решения. Найдите в старом проекте цепочку $event->getServer()->getHost(). Замените её на $event->getHost(), порт получите аналогично. Проверьте все типы событий, которые использует приложение, и удалите зависимость основного кода от старого метода.

Все getter отказа и обработчик commandFailed

Тринадцать карточек содержат полные сигнатуры, параметры, результат, ошибки, версии, границы и два применения. Исторический getServer имеет два реально выполняемых применения в отдельном архиве. Современные методы не подменяются старыми.

Связать диагностику с прикладным решением

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

Дальше: пары Started/Succeeded и чтение ответа, SDAM и heartbeat, индексы и ограниченный каталог, агрегационные отчёты, частичные результаты записи и восстановление. Для формы входа полезны передача полей формы и различие списка PHP и массива BSON.