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

Что получит диспетчер после отправки пакета

Машина уехала со склада. В системе нужна карточка отгрузки D-101 и запись EV-101 для журнала. Перед закрытием смены сотрудник должен увидеть, какие пары готовы, где не хватает события, а где связь требует разбирательства. В этой главе построим такую ведомость и выясним, почему сообщение «ошибка пакета» ещё не означает, что отгрузка не сохранена.

Представьте два журнала на рабочем столе: карточки отгрузок и записи событий. EV-101 ссылается на номер D-101. Такая модель объясняет назначение полей, но не даёт автоматического внешнего ключа или общей атомарности. MongoDB допускает событие с отсутствующей отгрузкой, пока приложение отдельно не обеспечивает согласованность.

Здесь уже нужны массивы и именованные ключи, вызовы функций, try/catch и исключения и первая выборка документов для экрана. Сам новый инструмент начинаем с двух вставок и наблюдаемого результата. Для отправки в одну коллекцию сначала можно пройти очередь импорта и обычный BulkWrite.

Как запустить отдельную учебную отгрузку

Откройте архив любого примера. В нём example.php с рабочим сценарием, dispatch-lab.php с подключением, чтением квитанций и выводом ведомости, а также README.txt с командами запуска. example.php подключает helper через require, затем runDispatch создаёт две пустые собственные коллекции и передаёт их в функцию сценария как $ship и $events.

Команда доступна с MongoDB Server 8.0 и ext-mongodb 2.1.0. Подготовленное окружение этого набора: PHP CLI 8.5.11 x64, ext-mongodb 2.5.5, mongodb/mongodb 2.5.0, standalone MongoDB 8.0.34. В README указано, как запустить отдельный сервер на 127.0.0.1:27075, установить библиотеку через Composer и задать PHPMAN_MONGODB_URI и PHPMAN_MONGODB_DATABASE. Строка подключения включает directConnection=true и retryWrites=false; имя учебной базы — php_manual_lab. Другой адрес или тип сервера helper отклоняет.

Валидатор только учебной коллекции events требует поля _id, shipment и kind; shipment должен быть строкой, kind — dispatched. validationAction=error отклоняет неправильный документ. Чужие коллекции и общие настройки сервера не изменяются. Для каждого запуска используются новые случайные имена; счётчики ролей до создания, после создания и после очистки должны быть 0 → 1 → 0 для каждой коллекции.

После команды php example.php ожидается указанная под примером строка. Откройте result.html как готовую ведомость; те же колонки и строки находятся в result.json. metrics.json содержит версии, условия проверки и журнал двух пространств имён. Ошибка подключения, неожиданная ошибка записи или несовпадение проверок завершает программу с ненулевым кодом; успешный результат при этом не подставляется. Автоматических повторов записи и циклов восстановления здесь нет.

Создать отгрузку и запись журнала одним пакетом

После погрузки сотруднику нужно открыть карточку отгрузки, а диспетчеру — увидеть соответствующее событие.

Входные данные

Изначально коллекции пусты. D-101 — номер отгрузки, EV-101 — собственный идентификатор записи журнала. Поле shipment связывает две записи.

Главное действие

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

$batch = new BulkWriteCommand();
$batch->insertOne($ordersNamespace, ['_id' => 'D-101', 'state' => 'отгружена']);
$batch->insertOne($eventsNamespace, ['_id' => 'EV-101', 'shipment' => 'D-101', 'kind' => 'dispatched']);
$result = $manager->executeBulkWriteCommand($batch);

new создаёт отдельный объект пакета. Стрелка -> вызывает его метод. Первый аргумент insertOne — адрес коллекции, второй — массив полей документа; запись ключ => значение задаёт одно поле. Первая операция относится к shipments, вторая — к events. $manager отправляет накопленные действия, а присваивание $result = сохраняет возвращённую квитанцию. В полном примере shipmentDoc и dispatchEvent только составляют массивы; их объявления находятся в dispatch-lab.php и сами в базу не пишут.

Что получим

Namespace — строка из имени базы и имени коллекции, разделённых точкой. В приложении getNamespace() берёт её из объекта коллекции. Одна передача пакета приложением может включать несколько серверных запросов при разделении большой партии драйвером.

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

Полный контракт объекта: BulkWriteCommand. Общие и подробные ответы разобраны в карточке BulkWriteCommandResult.

<?php
declare(strict_types=1);
require __DIR__.'/dispatch-lab.php';
use MongoDB\Collection;
use MongoDB\Driver\{Manager,BulkWriteCommand,BulkWriteCommandResult};

runDispatch('mongodb137-dispatch-plan-and-send', 'Создать отгрузку и запись журнала одним пакетом', ['Коллекция', 'Ключ', 'Что сохранилось'],
    function (Manager $manager,Collection $ship,Collection $events): array {
        $bulk=new BulkWriteCommand();
        $bulk->insertOne($ship->getNamespace(),shipmentDoc('D-101'));
        $bulk->insertOne($events->getNamespace(),dispatchEvent('EV-101','D-101'));
        $staged=count($bulk);
        $before=[$ship->countDocuments([]),$events->countDocuments([])];
        $result=submitDispatch($manager,$bulk);
        $s=$ship->findOne(['_id'=>'D-101']);
        $e=$events->findOne(['_id'=>'EV-101']);
        $checks['queue_only_before_submit'] = $staged===2 && $before===[0,0];
        $checks['two_acknowledged_inserts'] = $result->isAcknowledged() && $result->getInsertedCount()===2;
        $checks['linked_records'] = $e['shipment']===$s['_id'] && $s['state']==='отгружена';
        $rows=[['Отгрузки',$s['_id'],$s['state']],['Журнал',$e['_id'],'ссылка на '.$e['shipment']]];
        return [$rows,$checks,'D-101 отгружена. В журнале создана EV-101.'];
    }
);

D-101 отгружена. В журнале создана EV-101.

Открыть ведомость запуска · Скачать строки ведомости в JSON

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

Прочитать краткую квитанцию смены

Руководителю нужен итог смены. Число добавленных документов и число отправленных машин отвечают на разные вопросы.

Входные данные

Две отгрузки D-201 и D-202, у каждой ровно одно событие. Запрошено подтверждение записи w=1 без verboseResults.

Главное действие

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

$allInserted = $result->getInsertedCount();
$sent = $ship->countDocuments(['state' => 'отгружена']);

getInsertedCount() не принимает аргументов и возвращает PHP int. Он складывает вставки во всех коллекциях этой команды. countDocuments() выполняет отдельный запрос к выбранной коллекции по условию. Строка фильтра state => отгружена относится к карточкам, kind => dispatched — к событиям. В двух маленьких собственных коллекциях посторонних смен нет.

Что получим

Четыре вставки означают четыре документа. В отчёте о количестве отгрузок показываем два. При verboseResults=false подробные карты операций равны null; это штатный режим.

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

<?php
declare(strict_types=1);
require __DIR__.'/dispatch-lab.php';
use MongoDB\Collection;
use MongoDB\Driver\{Manager,BulkWriteCommand,BulkWriteCommandResult};

runDispatch('mongodb137-dispatch-shift-receipt', 'Прочитать краткую квитанцию смены', ['Как считаем', 'Количество'],
    function (Manager $manager,Collection $ship,Collection $events): array {
        $bulk=new BulkWriteCommand();
        foreach (['201','202'] as $serial) {
            $bulk->insertOne($ship->getNamespace(),shipmentDoc('D-'.$serial));
            $bulk->insertOne($events->getNamespace(),dispatchEvent('EV-'.$serial,'D-'.$serial));
        }
        $result=submitDispatch($manager,$bulk);
        $s=$ship->countDocuments(['state'=>'отгружена']);
        $e=$events->countDocuments(['kind'=>'dispatched']);
        $checks['summary_ack'] = $result->isAcknowledged() && $result->getInsertedCount()===4;
        $checks['no_verbose_maps'] = $result->getInsertResults()===null && $result->getUpdateResults()===null && $result->getDeleteResults()===null;
        $checks['both_collections_read'] = $s===2 && $e===2;
        $rows=[['Добавлено документов по квитанции',$result->getInsertedCount()],['Карточки отгрузки',$s],['События журнала',$e]];
        return [$rows,$checks,'Смена оформила 2 отгрузки и 2 события, всего 4 вставки.'];
    }
);

Смена оформила 2 отгрузки и 2 события, всего 4 вставки.

Открыть ведомость запуска · Скачать строки ведомости в JSON

Попробуйте самостоятельно. Уберите из входа D-202 с парным событием. Пересчитайте обе прикладные метрики и общий счётчик.

Сопоставить позицию квитанции с коллекцией

Ведомость должна подписать каждую операцию именем коллекции и бизнес-номером. Для этого нужна подробная квитанция.

Входные данные

В D-301 уже есть состояние «на рампе». Четыре действия в общем пакете: обновить D-301, добавить EV-301, добавить D-302, добавить EV-302.

Главное действие

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

$inserts = $result->getInsertResults();
$id = $inserts->get('2')->get('insertedId');  // D-302

true включает подробный ответ до отправки. getInsertResults() возвращает BSON Document, а get("2") читает поле с именем исходной позиции. Следующий get("insertedId") извлекает ключ D-302. В полной программе resultEntries() переводит документ в PHP-массив с сохранением ключей, затем foreach сопоставляет их с заранее известным планом. Числовые поля внутри BSON могут быть Int64: smallCount() переводит только маленькие учебные значения в int. Для произвольных 64-битных величин нужен контроль диапазона.

Что получим

Позиция 2 в карте вставок означает третье действие всего пакета. Отсчёт идёт с нуля. Преобразование в список с array_values() потеряло бы эту связь.

Индекс и _id имеют разные назначения. После формирования другого пакета индексы начнутся заново, ключи документов сохранят свой смысл.

Методы чтения имеют отдельные карточки: BulkWriteCommandResult::getInsertResults() и BulkWriteCommandResult::getUpdateResults().

<?php
declare(strict_types=1);
require __DIR__.'/dispatch-lab.php';
use MongoDB\Collection;
use MongoDB\Driver\{Manager,BulkWriteCommand,BulkWriteCommandResult};

runDispatch('mongodb137-dispatch-operation-map', 'Сопоставить позицию квитанции с коллекцией', ['Индекс', 'Куда писали', 'Ключ', 'Итог'],
    function (Manager $manager,Collection $ship,Collection $events): array {
        $ship->insertOne(shipmentDoc('D-301','на рампе'));
        $s=$ship->getNamespace(); $e=$events->getNamespace();
        $bulk=new BulkWriteCommand(['verboseResults'=>true]);
        $bulk->updateOne($s,['_id'=>'D-301'],['$set'=>['state'=>'отгружена']]);
        $bulk->insertOne($e,dispatchEvent('EV-301','D-301'));
        $bulk->insertOne($s,shipmentDoc('D-302'));
        $bulk->insertOne($e,dispatchEvent('EV-302','D-302'));
        $result=submitDispatch($manager,$bulk);
        $updates=resultEntries($result->getUpdateResults());
        $inserts=resultEntries($result->getInsertResults());
        $updated=$ship->findOne(['_id'=>'D-301']);
        $rows=[[0,'Отгрузки',$updated['_id'],'изменено '.smallCount($updates[0]['modifiedCount'])]];
        foreach ([1=>'Журнал',2=>'Отгрузки',3=>'Журнал'] as $position=>$role) {
            $rows[]=[$position,$role,$inserts[$position]['insertedId'],'вставлено'];
        }
        $checks['original_offsets_retained'] = array_keys($updates)===[0] && array_keys($inserts)===[1,2,3];
        $checks['actual_target_keys'] = $updated['state']==='отгружена' && $events->findOne(['_id'=>'EV-301'])['shipment']==='D-301' && $ship->findOne(['_id'=>'D-302'])['state']==='отгружена' && $events->findOne(['_id'=>'EV-302'])['shipment']==='D-302';
        $checks['detail_matches_summary'] = smallCount($updates[0]['matchedCount'])===$result->getMatchedCount() && $result->getMatchedCount()===1 && smallCount($updates[0]['modifiedCount'])===$result->getModifiedCount() && $result->getInsertedCount()===count($inserts);
        return [$rows,$checks,'Позиция 0 изменила отгрузку. Вставки сохранили номера 1, 2 и 3.'];
    }
);

Позиция 0 изменила отгрузку. Вставки сохранили номера 1, 2 и 3.

Открыть ведомость запуска · Скачать строки ведомости в JSON

Попробуйте самостоятельно. Поместите обновление между вставками. Найдите «дырку» в числовых ключах карты вставок и назовите отвечающую за неё операцию.

Обнаружить событие, для которого переход состояния не состоялся

Инженер объединил перевод заявки в «отгружена» и создание события. На практике заказ может быть отменён к моменту обработки.

Входные данные

В базе D-401 уже отменена. Фильтр обновления разрешает переход лишь со статуса «на рампе». Вторая операция безусловно добавляет строку журнала.

Главное действие

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

$bulk->updateOne($shipNs, ['_id'=>'D-401', 'state'=>'на рампе'],
    ['$set'=>['state'=>'отгружена']]);

Два поля в фильтре проверяются вместе: нужен именно D-401 именно в состоянии «на рампе». $set обозначает установку указанного поля. Ноль совпадений завершает updateOne штатно, поэтому ordered=true не останавливает следующий insertOne. Здесь прямые getMatchedCount()/getModifiedCount() и подробные значения первой операции оба равны нулю. Метод не сообщает, почему фильтр не совпал: это выясняет контрольное чтение карточки.

Что получим

ordered задаёт порядок, но не превращает вторую запись в условное продолжение первой. Если событие разрешено лишь после фактического перехода, проверьте matchedCount и проектируйте сохранение с нужной атомарностью.

Пример намеренно воспроизводит ошибочную схему в отдельной лаборатории. Надёжная доставка событий и транзакции требуют другой организации записи и подходящего развёртывания MongoDB.

<?php
declare(strict_types=1);
require __DIR__.'/dispatch-lab.php';
use MongoDB\Collection;
use MongoDB\Driver\{Manager,BulkWriteCommand,BulkWriteCommandResult};

runDispatch('mongodb137-dispatch-guarded-transition', 'Обнаружить событие, для которого переход состояния не состоялся', ['Что проверяем', 'Результат', 'Как прочитать'],
    function (Manager $manager,Collection $ship,Collection $events): array {
        $ship->insertOne(shipmentDoc('D-401','отменена'));
        $bulk=new BulkWriteCommand(['ordered'=>true,'verboseResults'=>true]);
        $bulk->updateOne($ship->getNamespace(),['_id'=>'D-401','state'=>'на рампе'],['$set'=>['state'=>'отгружена']]);
        $bulk->insertOne($events->getNamespace(),dispatchEvent('EV-401','D-401'));
        $result=submitDispatch($manager,$bulk);
        $detail=resultEntries($result->getUpdateResults());
        $matched=smallCount($detail[0]['matchedCount']);
        $s=$ship->findOne(['_id'=>'D-401']); $e=$events->findOne(['_id'=>'EV-401']);
        $checks['guard_matched_zero'] = $matched===0 && smallCount($detail[0]['modifiedCount'])===0 && $result->getMatchedCount()===0 && $result->getModifiedCount()===0;
        $checks['second_write_ran'] = $result->getInsertedCount()===1 && $e['shipment']===$s['_id'];
        $checks['original_state_unchanged'] = $s['state']==='отменена';
        $rows=[['Условное обновление',$matched,'совпадений'],[$s['_id'],$s['state'],'состояние в базе'],[$e['_id'],$e['kind'],'сверить событие']];
        return [$rows,$checks,'D-401 отменена. Условие обновления не совпало, но EV-401 создана.'];
    }
);

D-401 отменена. Условие обновления не совпало, но EV-401 создана.

Открыть ведомость запуска · Скачать строки ведомости в JSON

Попробуйте самостоятельно. Задайте исходное состояние «на рампе». Сравните matchedCount, modifiedCount и запись журнала для двух запусков.

Отделить сохранённую отгрузку от сбоя журнала

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

Входные данные

Сервер проверяет, что в журнале поле kind равно dispatched. Вторая запись содержит опечатку dispatch_typo. Третья должна была создать следующую отгрузку.

Главное действие

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

$partial = $error->getPartialResult();
$issues = $error->getWriteErrors();
$code = $issues[1]->getCode(); // 121

try передаёт управление в catch только при исключении. Учебная expectEventRejection() принимает лишь одну ошибку нужного индекса с кодом 121; неожиданный отказ выбрасывается дальше. У BulkWriteCommandException есть карта отдельных WriteError. getPartialResult() даёт сохранённую часть квитанции, а ?-> вызывает метод только при ненулевом объекте. Если объект равен null, выражение тоже вернёт null, а не число 0.

Что получим

Команда без транзакции допускает частичный результат даже при ordered=true. Один подтверждённый документ остаётся на месте, исключение ссылается на другой документ в другой коллекции.

При ошибке до любых подтверждённых успешных действий getPartialResult() может вернуть null. При сетевом обрыве отсутствие ответа само по себе ещё не устанавливает судьбу записи.

Проверьте границу между отказом записи и ошибкой подтверждения. Продолжение независимых строк показано в следующем примере.

<?php
declare(strict_types=1);
require __DIR__.'/dispatch-lab.php';
use MongoDB\Collection;
use MongoDB\Driver\{Manager,BulkWriteCommand,BulkWriteCommandResult};

runDispatch('mongodb137-dispatch-partial-log', 'Отделить сохранённую отгрузку от сбоя журнала', ['Индекс', 'Ключ', 'Фактическая судьба'],
    function (Manager $manager,Collection $ship,Collection $events): array {
        $bulk=new BulkWriteCommand(['ordered'=>true,'verboseResults'=>true]);
        $bulk->insertOne($ship->getNamespace(),shipmentDoc('D-501'));
        $bulk->insertOne($events->getNamespace(),dispatchEvent('EV-501','D-501','dispatch_typo'));
        $bulk->insertOne($ship->getNamespace(),shipmentDoc('D-502'));
        $error=expectEventRejection($manager,$bulk,1);
        $partial=$error->getPartialResult();
        $details=resultEntries($partial?->getInsertResults());
        $s=$ship->findOne(['_id'=>'D-501']);
        $e=$events->findOne(['_id'=>'EV-501']);
        $later=$ship->findOne(['_id'=>'D-502']);
        $checks['first_persisted'] = $s['state']==='отгружена' && $partial?->getInsertedCount()===1 && ($details[0]['insertedId'] ?? null)===$s['_id'];
        $checks['event_refused'] = $error->getWriteErrors()[1]->getCode()===121 && $e===null;
        $checks['ordered_tail_skipped'] = $later===null && array_keys($details)===[0];
        $rows=[[0,$s['_id'],$s['state']],[1,'EV-501',$e===null?'отказ 121':'есть'],[2,'D-502',$later===null?'после отказа не выполнялась':'есть']];
        return [$rows,$checks,'D-501 сохранилась, EV-501 отклонена, D-502 не выполнялась.'];
    }
);

D-501 сохранилась, EV-501 отклонена, D-502 не выполнялась.

Открыть ведомость запуска · Скачать строки ведомости в JSON

Попробуйте самостоятельно. Исправьте kind в копии программы и проследите, доходит ли пакет до D-502. В уже обработанной поставке не отправляйте весь прежний пакет повторно.

После ошибки большой вставки автор хочет повторять документы по одному и не знает, что уже сохранилось. Здесь первый документ реально сохраняется, а валидатор отклоняет второй в другой коллекции: перед исправлением нужно установить судьбу каждого действия. Практический вопрос: is PyMongo / MongoDB insert_many transactional?. Контракт PHP API и MongoDB проверяется по официальным источникам этой главы; синтаксис старого Java/Python-драйвера сюда не переносится.

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

Очередь содержит две независимые заявки. Ошибка формата журнала у одной не должна скрывать результат обработки другой.

Входные данные

План из четырёх операций: пара D-601/EV-601 и пара D-602/EV-602. Только EV-601 содержит недопустимый kind.

Главное действие

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

$batch = new BulkWriteCommand(['ordered'=>false, 'verboseResults'=>true]);

false отключает остановку на первой ошибке отдельной записи. Ошибки всё равно приводят к исключению после попыток обработки остальных операций; успешные результаты берём из partialResult. ksort() здесь упорядочивает ключи полученной карты лишь для проверки состава индексов, а не управляет сервером. Два findOne() на каждую пару показывают реальное состояние после команды.

Что получим

Операции не зависят от чтения предыдущего результата. Их номера сохраняются для разбора, но не сообщают порядок фактического выполнения.

Связь в этом опыте задана идентификаторами, внешнего ключа MongoDB здесь нет. Unordered не обеспечивает атомарность пары и не предназначен для исполнения зависимых шагов по порядку.

<?php
declare(strict_types=1);
require __DIR__.'/dispatch-lab.php';
use MongoDB\Collection;
use MongoDB\Driver\{Manager,BulkWriteCommand,BulkWriteCommandResult};

runDispatch('mongodb137-dispatch-independent-rows', 'Продолжить независимую обработку после ошибочного события', ['Отгрузка', 'Карточка', 'Журнал', 'Действие'],
    function (Manager $manager,Collection $ship,Collection $events): array {
        $bulk=new BulkWriteCommand(['ordered'=>false,'verboseResults'=>true]);
        $bulk->insertOne($ship->getNamespace(),shipmentDoc('D-601'));
        $bulk->insertOne($events->getNamespace(),dispatchEvent('EV-601','D-601','wrong'));
        $bulk->insertOne($ship->getNamespace(),shipmentDoc('D-602'));
        $bulk->insertOne($events->getNamespace(),dispatchEvent('EV-602','D-602'));
        $error=expectEventRejection($manager,$bulk,1);
        $partial=$error->getPartialResult();
        $success=resultEntries($partial?->getInsertResults()) ?? [];
        ksort($success);
        $rows=[];
        foreach ([['D-601','EV-601'],['D-602','EV-602']] as [$id,$eventId]) {
            $s=$ship->findOne(['_id'=>$id]);
            $e=$events->findOne(['_id'=>$eventId]);
            $rows[]=[$id,$s['state'] ?? 'нет',$e['_id'] ?? 'нет',$e===null?'Исправить журнал':'Готово'];
        }
        $checks['successful_original_indexes'] = array_keys($success)===[0,2,3] && $partial?->getInsertedCount()===3;
        $checks['one_error_at_one'] = array_keys($error->getWriteErrors())===[1];
        $checks['independent_row_complete'] = $events->findOne(['_id'=>'EV-602'])['shipment']==='D-602' && $ship->countDocuments([])===2 && $events->countDocuments([])===1;
        return [$rows,$checks,'D-602 оформлена полностью. Для D-601 нужно исправить только журнал.'];
    }
);

D-602 оформлена полностью. Для D-601 нужно исправить только журнал.

Открыть ведомость запуска · Скачать строки ведомости в JSON

Попробуйте самостоятельно. Поменяйте ошибочную строку у второй пары. Проверьте, какие входные индексы придут в getWriteErrors(), а какие попадут в подробную квитанцию.

Вопрос смешивает порядок обработки и возможность повторных попыток. В нашей лаборатории unordered продолжает остальные независимые действия после ошибки строки; автоматических повторов нет, retryWrites=false и standalone зафиксированы явно. Практический вопрос: MongoDB retryable writes in unordered bulk operation. Контракт PHP API и MongoDB проверяется по официальным источникам этой главы; синтаксис старого Java/Python-драйвера сюда не переносится.

Дополнить только отсутствующее событие после сверки

После сверки сотрудник разрешил исправить только журнал. Состояние отгрузки и фактический факт отправки уже подтверждены.

Входные данные

Первый пакет действительно сохраняет D-701 и получает код 121 на EV-701. До исправления программа читает статус D-701 и убеждается в отсутствии записи с нужным ключом.

Главное действие

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

$key = ['_id'=>'EV-701', 'shipment'=>'D-701', 'kind'=>'dispatched'];
$repair->updateOne($eventsNs, $key, ['$setOnInsert'=>['source'=>'manual-reconciliation']], ['upsert'=>true]);

approvedRepair — заранее заданный учебный вход, который представляет отдельное решение сотрудника исправить EV-701 для D-701. Это не результат автоматического обработчика исключения. Проверки before выполняются непосредственно перед новым пакетом. В фильтре updateOne перечислены _id, shipment и kind; upsert=true создаёт документ при отсутствии совпадения. $setOnInsert добавляет source только при создании. В команду не входит ни insert, ни update коллекции отгрузок.

Что получим

Upsert, который создал документ, попадает в getUpsertedCount() и карту getUpdateResults(). Повтор идентичного запроса при неизменном документе нашёл бы существующий ключ и не вставил бы второй экземпляр. Конфликт с чужим содержимым под тем же _id требует разбирательства.

Этот обработчик требует явного решения оператора и сверки состояния. Одно чтение не блокирует параллельную отмену отгрузки. Для атомарной проверки разных документов нужно проектировать транзакцию на подходящем развёртывании или хранить подлежащее подтверждению событие вместе с состоянием.

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

<?php
declare(strict_types=1);
require __DIR__.'/dispatch-lab.php';
use MongoDB\Collection;
use MongoDB\Driver\{Manager,BulkWriteCommand,BulkWriteCommandResult};

runDispatch('mongodb137-dispatch-repair-event', 'Дополнить только отсутствующее событие после сверки', ['Когда', 'Отгрузка', 'Событие'],
    function (Manager $manager,Collection $ship,Collection $events): array {
        $first=new BulkWriteCommand(['ordered'=>true]);
        $first->insertOne($ship->getNamespace(),shipmentDoc('D-701'));
        $first->insertOne($events->getNamespace(),dispatchEvent('EV-701','D-701','bad-kind'));
        expectEventRejection($manager,$first,1);
        // A fixed teaching input represents a separately approved reconciliation, not an automatic retry.
        $approvedRepair=['shipment'=>'D-701','event'=>'EV-701'];
        $shipBefore=$ship->findOne(['_id'=>'D-701']);
        $eventBefore=$events->findOne(['_id'=>'EV-701']);
        if ($approvedRepair!==['shipment'=>'D-701','event'=>'EV-701'] || $shipBefore===null || $shipBefore['state']!=='отгружена' || $eventBefore!==null) {
            throw new RuntimeException('Repair precondition failed');
        }
        // The journal has its own stable key. A conflicting payload with that key cannot be overwritten.
        $repair=new BulkWriteCommand(['verboseResults'=>true]);
        $key=dispatchEvent('EV-701','D-701');
        $repair->updateOne($events->getNamespace(),$key,['$setOnInsert'=>['source'=>'manual-reconciliation']],['upsert'=>true]);
        $report=submitDispatch($manager,$repair);
        $detail=resultEntries($report->getUpdateResults());
        $shipAfter=$ship->findOne(['_id'=>'D-701']);
        $eventAfter=$events->findOne(['_id'=>'EV-701']);
        $checks['repaired_one_event'] = count($repair)===1 && $report->getUpsertedCount()===1 && $report->getInsertedCount()===0 && ($detail[0]['upsertedId'] ?? null)==='EV-701';
        $checks['original_untouched'] = $shipAfter===$shipBefore && $ship->countDocuments([])===1;
        $checks['correct_relationship'] = $eventAfter['shipment']==='D-701' && $eventAfter['kind']==='dispatched' && $events->countDocuments([])===1;
        $rows=[['До сверки',$shipBefore['_id'],$eventBefore['_id'] ?? 'нет'],['После исправления',$shipAfter['_id'],$eventAfter['_id']]];
        return [$rows,$checks,'Для существующей D-701 добавлена EV-701. Отгрузка осталась в одном экземпляре.'];
    }
);

Для существующей D-701 добавлена EV-701. Отгрузка осталась в одном экземпляре.

Открыть ведомость запуска · Скачать строки ведомости в JSON

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

Автор ожидает список upsert и при изменении уже существующего документа. В нашем восстановлении журнала отдельно читаем getUpsertedCount и upsertedId: они относятся к созданию отсутствующего события, а не ко всем обновлениям. Практический вопрос: mongo BulkWriteOperation with upsert option doesn't return upserted entries for updates. Контракт PHP API и MongoDB проверяется по официальным источникам этой главы; синтаксис старого Java/Python-драйвера сюда не переносится.

Составить ведомость перед закрытием смены

Перед закрытием смены диспетчер проверяет четыре ожидаемых задания. Одна общая цифра вставок не укажет, какой именно заказ можно закрыть.

Входные данные

Исходный список содержит D-801…D-804 и ожидаемые ключи событий. В учебной базе созданы обе стороны для 801, только карточка для 802, только событие для 803. Для 804 совпадений нет.

Главное действие

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

$s = $sIndex[$id] ?? null;
$e = $eIndex[$eventIds[$i]] ?? null;

В начале программы четыре вставки подготавливают разные исходные случаи. После комментария об окончании подготовки экран выполняет только чтения. Оператор $in ограничивает запрос списком нужных ключей; projection выбирает полезные поля, _id остаётся доступен. PHP-массивы sIndex и eIndex становятся справочниками по _id. Выражение ?? null даёт null для отсутствующей записи. match(true) берёт первое подходящее условие сверху вниз, поэтому сначала проверяется отсутствие обеих сторон, затем состояние и связь.

Что получим

Действие «Добавить запись в журнал» предлагает оператору перейти к отдельной сверке. Одно событие без исходной отгрузки не даёт оснований объявлять, что товар отправлен. У отсутствующих обеих сторон сначала проверяют саму задачу отправки.

Список относится к небольшой закрываемой смене. Два чтения показаны на неизменяемом во время сверки наборе; на работающем складе параллельные изменения могут потребовать ещё одной сверки или согласованного чтения.

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

<?php
declare(strict_types=1);
require __DIR__.'/dispatch-lab.php';
use MongoDB\Collection;
use MongoDB\Driver\{Manager,BulkWriteCommand,BulkWriteCommandResult};

runDispatch('mongodb137-dispatch-dispatch-desk', 'Составить ведомость перед закрытием смены', ['Номер задания', 'Отгрузка', 'Событие', 'Действие'],
    function (Manager $manager,Collection $ship,Collection $events): array {
        $bulk=new BulkWriteCommand();
        $bulk->insertOne($ship->getNamespace(),shipmentDoc('D-801'));
        $bulk->insertOne($events->getNamespace(),dispatchEvent('EV-801','D-801'));
        $bulk->insertOne($ship->getNamespace(),shipmentDoc('D-802'));
        $bulk->insertOne($events->getNamespace(),dispatchEvent('EV-803','D-803'));
        $written=submitDispatch($manager,$bulk);
        // Fixture preparation ends here. The following screen only reads the two collections.
        $beforeScreen=[$ship->find([],['sort'=>['_id'=>1]])->toArray(),$events->find([],['sort'=>['_id'=>1]])->toArray()];
        $ids=['D-801','D-802','D-803','D-804'];
        $eventIds=['EV-801','EV-802','EV-803','EV-804'];
        $sIndex=[]; $eIndex=[];
        foreach ($ship->find(['_id'=>['$in'=>$ids]],['projection'=>['state'=>1]]) as $doc) { $sIndex[$doc['_id']]=$doc; }
        foreach ($events->find(['_id'=>['$in'=>$eventIds]],['projection'=>['shipment'=>1,'kind'=>1]]) as $doc) { $eIndex[$doc['_id']]=$doc; }
        $rows=[];
        foreach ($ids as $i=>$id) {
            $s=$sIndex[$id] ?? null; $e=$eIndex[$eventIds[$i]] ?? null;
            $decision=match(true) {
                $s===null && $e===null=>'Проверить исходное задание',
                $s===null || $s['state']!=='отгружена'=>'Разобрать связь вручную',
                $e===null=>'Добавить запись в журнал',
                $e['shipment']!==$id || $e['kind']!=='dispatched'=>'Разобрать связь вручную',
                default=>'Готово',
            };
            $rows[]=[$id,$s['state'] ?? 'нет',$e['_id'] ?? 'нет',$decision];
        }
        $checks['seed_receipt_matches_actual'] = $written->getInsertedCount()===4 && count($sIndex)===2 && count($eIndex)===2;
        $checks['four_distinct_decisions'] = count(array_unique(array_column($rows,3)))===4;
        $afterScreen=[$ship->find([],['sort'=>['_id'=>1]])->toArray(),$events->find([],['sort'=>['_id'=>1]])->toArray()];
        $checks['no_writes_by_screen'] = $beforeScreen===$afterScreen && count($afterScreen[0])===2 && count($afterScreen[1])===2;
        return [$rows,$checks,'Из четырёх заданий одно подтверждено обеими записями, три требуют разных действий.'];
    }
);

Из четырёх заданий одно подтверждено обеими записями, три требуют разных действий.

Открыть ведомость запуска · Скачать строки ведомости в JSON

Попробуйте самостоятельно. Задайте EV-801 связь с D-802. Проверьте, что строка 801 больше не считается полностью подтверждённой, хотя оба ключа существуют.

Как выбрать размер партии и следующий способ записи

Пакет уменьшает число отдельных отправок приложением. Большая партия может быть разделена драйвером по ограничениям размера; подробные карты требуют ответа и памяти для каждой успешной операции. Для итоговой цифры смены достаточно общих счётчиков, для построчного расследования полезен verboseResults. Объём, время и память измеряют на реальных размерах документов; режим unordered сам по себе не обещает ускорения.

Успешные отдельные записи, подтверждение сервера и прикладная согласованность — три разные проверки. Ошибка валидатора говорит, какой документ отклонён. Ошибка подтверждения или потерянный ответ могут оставить судьбу действия неизвестной. Не превращайте любой catch в повтор: сначала сохраните исходный план, индексы и ключи, затем установите состояние каждой записи.

Retryable writes — отдельная возможность драйвера и подходящего replica set/sharded развёртывания; на standalone она не поддерживается. В этой лаборатории retryWrites=false задан явно. Режим ordered влияет на порядок и продолжение после ошибки строки, а решение о ручном восстановлении остаётся отдельным действием.

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