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

Как отличить подготовленный импорт от сохранённого каталога

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

Представьте список поручений кладовщику: записать поручение и выполнить его — два отдельных шага. BulkWrite похож на такой список, но хранит только инструкции в памяти процесса PHP; это не долговечная фоновая очередь заданий. При завершении процесса неотправленный объект не сохранится автоматически. MongoDB хранит документы, например одну карточку с полями _id и qty. Артикул (SKU) обозначает вид товара, qty — число штук. Одна карточка с qty=4 не превращается в четыре операции.

$bulk = new MongoDB\Driver\BulkWrite();
$bulk->insert(['_id' => 'LAMP', 'qty' => 4]);
echo count($bulk); // 1

Здесь $bulk — переменная с объектом, new создаёт объект, -> вызывает его метод. Квадратные скобки задают поля документа: => связывает имя поля со значением, строка LAMP заключена в кавычки, число 4 записано без них. Точка с запятой завершает инструкцию. count читает местный счётчик. В этих трёх строках ещё нет отправки. В первом самостоятельном примере ниже добавлены соединение, проверка коллекции до записи и отдельное чтение после неё.

Для этого маршрута пригодятся ключи и значения массивов, аргументы и результат функции, объект и вызов метода, try/catch и finally и документ, коллекция и фильтр MongoDB. Namespace MongoDB — адрес вида «база.коллекция», а имя PHP-класса MongoDB\Driver\BulkWrite использует пространство имён языка. В строке адреса базы разделителем служит точка, в имени PHP-класса — обратная косая черта.

Как запустить пример и прочитать его файлы

Каждый ZIP содержит самостоятельные example.php, q137-helper.php и README.txt. Для CLI нужен PHP с ext-mongodb и отдельный учебный MongoDB standalone на 127.0.0.1:27075; библиотека Composer этим восьми программам не требуется. Сверенный стенд: PHP 8.5.11, ext-mongodb 2.5.5, MongoDB 8.0.34. Это версии стенда, а не заявление о последних доступных версиях. Команды запуска и две переменные окружения указаны в README.

Функция q137Lab создаёт собственную случайно названную коллекцию в php_manual_lab, передаёт её адрес программе и удаляет только эту коллекцию в finally. Она проверяет, что до начала коллекции не было и после очистки её снова нет. q137Seed добавляет исходные карточки; q137Read выполняет настоящий запрос, устанавливает карту типов в массивы и сортирует результат по _id. В учебной выдаче предел 30 документов, а самый большой набор здесь существенно меньше. Это ограниченное чтение учебного каталога, не универсальная выгрузка любого размера.

Программа выводит таблицу в терминал, сохраняет result.html и result.json, а metrics.json фиксирует проверки запуска. В коротких фрагментах ниже $manager и $ns уже подготовлены обвязкой; для самостоятельного запуска скачивайте полный пример. После изменения данных в упражнении пересчитайте ожидаемые $checks и таблицу: намеренно изменённый результат не должен выдаваться за первоначальную проверку. Проверки HTTP-формы описаны отдельно от запусков CLI.

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

На склад поступили четыре лампы. В каталоге будет один документ с артикулом LAMP и количеством 4. Подготовим запись, откроем каталог до отправки, затем отправим и прочитаем ещё раз.

Короткий фрагмент из программы

$bulk = new MongoDB\Driver\BulkWrite();
$bulk->insert(['_id'=>'LAMP', 'qty'=>4]);
echo count($bulk); // 1 операция подготовлена
$result = $manager->executeBulkWrite($ns, $bulk);
echo $result->getInsertedCount(); // 1 документ создан

Что увидит оператор

new создаёт объект в памяти PHP. insert добавляет описание одной операции. count вызывает метод счётчика этого объекта. Изменение в MongoDB выполняет executeBulkWrite, где $ns — имя базы и коллекции через точку. Возвращённый WriteResult содержит число созданных документов.

Границы решения

Номер операции, число документов и количество единиц товара имеют разные единицы измерения. В этой записи а) одна инструкция, б) один новый документ, в) четыре лампы. Для следующей отправки создают новый BulkWrite.

<?php
declare(strict_types=1);
use MongoDB\Driver\{Manager,BulkWrite,WriteResult,WriteError};
use MongoDB\Driver\Exception\BulkWriteException;
require __DIR__.'/q137-helper.php';

[$rows,$checks,$runtime,$counts]=q137Lab(static function(Manager $manager,string $db,string $ns): array {
    $bulk=new BulkWrite();
    $empty=count($bulk);
    $bulk->insert(['_id'=>'LAMP','qty'=>4]);
    $queued=count($bulk);
    $before=q137Read($manager,$ns,['_id'=>'LAMP']);
    $result=$manager->executeBulkWrite($ns,$bulk);
    $after=q137Read($manager,$ns,['_id'=>'LAMP']);
    $rows=[['Операций до insert',$empty],['Операций после insert',$queued],['Товаров до отправки',count($before)],
        ['Создано при отправке',$result->getInsertedCount()],['Остаток LAMP в базе',$after[0]['qty']]];
    $checks=['starts_empty'=>$empty===0,'one_queued'=>$queued===1,'not_yet_stored'=>$before===[],'result_type'=>$result instanceof WriteResult,
        'acknowledged'=>$result->isAcknowledged(),'one_created'=>$result->getInsertedCount()===1,'read_after'=>count($after)===1 && $after[0]['qty']===4];
    return [$rows,$checks];
});
q137Report('mongodb137-queue-first-send', 'Поставить товар в очередь и увидеть, когда он появился в базе', ['Что проверили', 'Результат'], $rows,$checks,$runtime,$counts);
foreach ($rows as [$label,$value]) {echo $label, ' — ', $value, PHP_EOL;}

Операций до insert — 0
Операций после insert — 1
Товаров до отправки — 0
Создано при отправке — 1
Остаток LAMP в базе — 4

Открыть таблицу фактического запуска · Скачать JSON результата.

Попробуйте изменить

Замените qty на 40. Какие две единицы в таблице останутся равными и почему?

Увидеть три совпадения у одной операции обновления

Редактор нажал «Показать все лампы». Три товара удовлетворяют фильтру, но один из них уже показывается. Как подписать в отчёте числа 1, 3 и 2?

Короткий фрагмент из программы

$bulk->update(['group'=>'lamp'], ['$set'=>['visible'=>true]], ['multi'=>true]);
echo count($bulk); // 1

Что увидит оператор

multi=true разрешает обработать несколько документов одной инструкцией. Количество добавленных инструкций известно до обращения к MongoDB. Сколько товаров подошло и сколько изменилось, сервер сообщает после исполнения. Кабель D вне фильтра остаётся скрытым.

Границы решения

Нельзя использовать count($bulk) как процент обработанных товаров. При широком фильтре одна инструкция может изменить тысячи документов. В учебной коллекции список явно ограничен четырьмя товарами.

<?php
declare(strict_types=1);
use MongoDB\Driver\{Manager,BulkWrite,WriteResult,WriteError};
use MongoDB\Driver\Exception\BulkWriteException;
require __DIR__.'/q137-helper.php';

[$rows,$checks,$runtime,$counts]=q137Lab(static function(Manager $manager,string $db,string $ns): array {
    $seed=q137Seed($manager,$ns,[['_id'=>'A','group'=>'lamp','visible'=>false],['_id'=>'B','group'=>'lamp','visible'=>true],
        ['_id'=>'C','group'=>'lamp','visible'=>false],['_id'=>'D','group'=>'cable','visible'=>false]]);
    $bulk=new BulkWrite();
    $bulk->update(['group'=>'lamp'],['$set'=>['visible'=>true]],['multi'=>true]);
    $queued=$bulk->count();
    $result=$manager->executeBulkWrite($ns,$bulk);
    $shown=q137Read($manager,$ns,['visible'=>true]);
    $outside=q137Read($manager,$ns,['_id'=>'D'])[0];
    $ids=implode(', ',array_column($shown,'_id'));
    $rows=[['Операций в очереди',$queued],['Подошло товаров',$result->getMatchedCount()],['Видимость изменилась',$result->getModifiedCount()],['Теперь показаны',$ids]];
    $checks=['four_seeded'=>$seed===4,'one_action'=>$queued===1,'matched_three'=>$result->getMatchedCount()===3,
        'changed_two'=>$result->getModifiedCount()===2,'shown_set'=>$ids==='A, B, C','untargeted'=>$outside['visible']===false];
    return [$rows,$checks];
});
q137Report('mongodb137-queue-fanout', 'Увидеть три совпадения у одной операции обновления', ['Что проверили', 'Результат'], $rows,$checks,$runtime,$counts);
foreach ($rows as [$label,$value]) {echo $label, ' — ', $value, PHP_EOL;}

Операций в очереди — 1
Подошло товаров — 3
Видимость изменилась — 2
Теперь показаны — A, B, C

Открыть таблицу фактического запуска · Скачать JSON результата.

Попробуйте изменить

Сделайте все три лампы видимыми до команды. Как должны измениться matchedCount, modifiedCount и число операций?

Разобрать три ответа на кнопку «Установить остаток»

Три строки импорта указывают одно и то же новое количество 8. У A уже 8, у B осталось 3, а X вообще нет в каталоге. Менеджеру нужны три разных подписи.

Короткий фрагмент из программы

if ($result->getMatchedCount() === 0) { return 'нет товара'; }
return $result->getModifiedCount() === 0 ? 'уже актуально' : 'обновлено';

Что увидит оператор

В этом разборе для каждой строки используется своя отправка, поэтому конкретные matched и modified можно отнести к соответствующему артикулу. У A matched=1 и modified=0. У X оба равны нулю. upsert=false запрещает создавать незнакомый артикул.

Границы решения

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

<?php
declare(strict_types=1);
use MongoDB\Driver\{Manager,BulkWrite,WriteResult,WriteError};
use MongoDB\Driver\Exception\BulkWriteException;
require __DIR__.'/q137-helper.php';

[$rows,$checks,$runtime,$counts]=q137Lab(static function(Manager $manager,string $db,string $ns): array {
    $seed=q137Seed($manager,$ns,[['_id'=>'A','qty'=>8],['_id'=>'B','qty'=>3]]);
    $requests=['A'=>8,'B'=>8,'X'=>8];
    $rows=[];$counts=[];
    foreach ($requests as $sku=>$qty) {
        $bulk=new BulkWrite();
        $bulk->update(['_id'=>$sku],['$set'=>['qty'=>$qty]],['upsert'=>false]);
        $result=$manager->executeBulkWrite($ns,$bulk);
        $matched=$result->getMatchedCount();$changed=$result->getModifiedCount();
        $stored=q137Read($manager,$ns,['_id'=>$sku]);
        $status=$matched===0 ? 'нет товара' : ($changed===0 ? 'уже актуально' : 'обновлено');
        $rows[]=[$sku,$status.' · в базе '.($stored===[] ? 'нет' : $stored[0]['qty'])];
        $counts[$sku]=[$matched,$changed];
    }
    $checks=['two_seeded'=>$seed===2,'three_requests'=>count($rows)===3,'already_current'=>$counts['A']===[1,0],
        'really_changed'=>$counts['B']===[1,1],'no_match'=>$counts['X']===[0,0],'two_remain'=>count(q137Read($manager,$ns))===2];
    return [$rows,$checks];
});
q137Report('mongodb137-queue-edit-outcomes', 'Разобрать три ответа на кнопку «Установить остаток»', ['Что проверили', 'Результат'], $rows,$checks,$runtime,$counts);
foreach ($rows as [$label,$value]) {echo $label, ' — ', $value, PHP_EOL;}

A — уже актуально · в базе 8
B — обновлено · в базе 8
X — нет товара · в базе нет

Открыть таблицу фактического запуска · Скачать JSON результата.

Попробуйте изменить

Замените начальное количество B на 8. У каких двух артикулов теперь совпадут и статус, и количество в базе?

В интерфейсе показано действие, а matched=1 и modified=0. Различаем совпадение фильтра и фактическое изменение с отдельным чтением результата. Реальная постановка на Stack Overflow. В исходной ситуации обработчик React отправлял значение количества при изменении состояния интерфейса. Здесь та же диагностическая потребность разобрана собственным PHP-примером: A уже имеет нужный остаток, B меняется, X отсутствует; отдельное чтение сверяет все три вывода. Этот пример объясняет ответ MongoDB и не подменяет собой исправление состояния React.

Сложить разнородные операции в одну квитанцию каталога

Импорт добавляет новый артикул, меняет остаток, снимает старый товар и ищет для обновления ещё не заведённый артикул. Менеджеру нужна короткая сводка вместо четырёх однотипных сообщений «готово».

Короткий фрагмент из программы

$bulk->insert(['_id'=>'NEW', 'qty'=>6]);
$bulk->update(['_id'=>'KEEP'], ['$set'=>['qty'=>4]]);
$bulk->delete(['_id'=>'OLD'], ['limit'=>1]);

Что увидит оператор

Четыре инструкции дали три фактических изменения. matched и modified описывают пересекающиеся сведения об обновлении KEEP, поэтому складывать все счётчики в общее число изменений нельзя. Количество сетевых команд тоже может отличаться от числа PHP-объектов и числа инструкций.

Границы решения

limit=1 у удаления ограничивает число удалённых документов. И в примере, и в рабочем импорте сначала выделите точный ключ товара. Несколько записей в пакете не становятся одной атомарной транзакцией.

<?php
declare(strict_types=1);
use MongoDB\Driver\{Manager,BulkWrite,WriteResult,WriteError};
use MongoDB\Driver\Exception\BulkWriteException;
require __DIR__.'/q137-helper.php';

[$rows,$checks,$runtime,$counts]=q137Lab(static function(Manager $manager,string $db,string $ns): array {
    $seed=q137Seed($manager,$ns,[['_id'=>'KEEP','qty'=>3],['_id'=>'OLD','qty'=>1]]);
    $bulk=new BulkWrite(['ordered'=>true]);
    $bulk->insert(['_id'=>'NEW','qty'=>6]);
    $bulk->update(['_id'=>'KEEP'],['$set'=>['qty'=>4]]);
    $bulk->delete(['_id'=>'OLD'],['limit'=>1]);
    $bulk->update(['_id'=>'ABSENT'],['$set'=>['qty'=>7]],['upsert'=>false]);
    $size=count($bulk);
    $result=$manager->executeBulkWrite($ns,$bulk);
    $catalog=q137Read($manager,$ns);
    $items=implode(', ',array_map(fn($d)=>$d['_id'].'='.$d['qty'],$catalog));
    $rows=[['Отправлено инструкций',$size],['Вставлено',$result->getInsertedCount()],['Подошло под обновление',$result->getMatchedCount()],
        ['Изменено обновлением',$result->getModifiedCount()],['Удалено',$result->getDeletedCount()],['Каталог после импорта',$items]];
    $checks=['seed'=>$seed===2,'queued_four'=>$size===4,'one_insert'=>$result->getInsertedCount()===1,'one_match'=>$result->getMatchedCount()===1,
        'one_change'=>$result->getModifiedCount()===1,'one_delete'=>$result->getDeletedCount()===1,'actual_items'=>$items==='KEEP=4, NEW=6'];
    return [$rows,$checks];
});
q137Report('mongodb137-queue-mixed-receipt', 'Сложить разнородные операции в одну квитанцию каталога', ['Что проверили', 'Результат'], $rows,$checks,$runtime,$counts);
foreach ($rows as [$label,$value]) {echo $label, ' — ', $value, PHP_EOL;}

Отправлено инструкций — 4
Вставлено — 1
Подошло под обновление — 1
Изменено обновлением — 1
Удалено — 1
Каталог после импорта — KEEP=4, NEW=6

Открыть таблицу фактического запуска · Скачать JSON результата.

Попробуйте изменить

Оставьте OLD за пределами фильтра удаления. Проверьте deletedCount и конечный перечень артикулов.

Как сохранить номер строки до фильтрации и разбиения

В CLI-сценариях строка CSV начинается заголовком action;sku;qty. Действие insert создаёт карточку, set устанавливает количество существующего товара, delete удаляет товар. Номер физической строки сохраняется до отбора; отсчёт начинается с единицы и включает заголовок. Внутренняя позиция массива и индекс операции начинаются с нуля.

q137Parse — обычная функция разбора, она не обращается к базе. preg_match проверяет согласованный формат артикула и количества; явное приведение (int) выполняется только после проверки. q137Add переводит допустимое действие в insert/update/delete. Для set используется $set: имя оператора стоит в одинарных кавычках, чтобы PHP не пытался подставить переменную $set. Фильтр [_id => артикул] ограничивает правку нужной карточкой. multi=false, upsert=false и limit=1 не дают этому учебному действию незаметно превратиться в массовое изменение или создание.

q137Dispatch создаёт собственные $bulk и $map для каждого вызова. Сначала q137Add успешно добавляет операцию; только затем в карту добавляется исходная строка. После executeBulkWrite функция проверяет подтверждение и возвращает суммарные inserted, matched, modified, deleted, queued и список issues. В catch она принимает только подтверждённый частичный результат с индивидуальными ошибками и без WriteConcernError; иной отказ передаёт выше. Это позволяет не подменять неизвестный исход нулём. Внутренний список ошибок обходится foreach, а исходный индекс читается методом getIndex().

array_chunk($parsed['valid'], 2) делит отобранные строки на массивы длиной не более двух. Это учебная граница приложения, выбранная для наглядного сопоставления; она не является максимальным размером пакета MongoDB. Парсер здесь работает с целой короткой строкой в памяти. Для большого производственного файла потребуются потоковое чтение, полноценный CSV-парсер и сохранение координат записи; чтение файлов и регулярные выражения разбираются отдельно.

Вернуть конфликт записи к строке файла после двух пропусков

Заголовок занимает первую строку CSV, третья строка пустая, четвёртая содержит отрицательный остаток. В пятой строке уже существующий EXIST. MongoDB сообщает индекс 1. Нужно подсветить пятую строку, а не первую или вторую.

Короткий фрагмент из программы

// Добавлять запись в карту только вместе с успешным добавлением в BulkWrite.
$bulk->insert($document);
$sourceLines[] = $physicalLine;
// Позже в обработчике ошибок:
$line = $sourceLines[$writeError->getIndex()];

Что увидит оператор

После фильтрации до драйвера дошли строки 2, 5 и 6. Внутри одного BulkWrite они стали операциями с индексами 0, 1 и 2. Код 11000 и отдельная карта дают ответ без разбора текста сообщения. В учебном формате одна запись занимает одну физическую строку, кавычки и переносы внутри поля не предусмотрены.

Границы решения

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

<?php
declare(strict_types=1);
use MongoDB\Driver\{Manager,BulkWrite,WriteResult,WriteError};
use MongoDB\Driver\Exception\BulkWriteException;
require __DIR__.'/q137-helper.php';

[$rows,$checks,$runtime,$counts]=q137Lab(static function(Manager $manager,string $db,string $ns): array {
    $seed=q137Seed($manager,$ns,[['_id'=>'EXIST','qty'=>1]]);
    $input="action;sku;qty\ninsert;NEW;2\n\ninsert;BAD;-7\ninsert;EXIST;9\ninsert;TAIL;4";
    $parsed=q137Parse($input);
    $sent=q137Dispatch($manager,$ns,$parsed['valid'],false);
    $issue=$sent['issues'][0];
    $beforeConflict=q137Read($manager,$ns,['_id'=>'EXIST'])[0]['qty'];
    $rows=[['Пустая строка',$parsed['blanks'][0]],['Ошибка до отправки',$parsed['invalid'][0]],['Индекс в MongoDB',$issue['index']],
        ['Строка исходного CSV',$issue['line']],['Артикул и код',$issue['sku'].' · '.$issue['code']],['Вставлено остальных',$sent['inserted']]];
    $checks=['one_seed'=>$seed===1,'blanks'=>$parsed['blanks']===[3],'rejected_locally'=>$parsed['invalid']===[4],
        'sent_three'=>$sent['queued']===3,'mapped_error'=>$issue===['index'=>1,'line'=>5,'sku'=>'EXIST','code'=>11000],
        'unchanged'=>$beforeConflict===1,'others_written'=>$sent['inserted']===2 && count(q137Read($manager,$ns))===3];
    return [$rows,$checks];
});
q137Report('mongodb137-queue-source-lines', 'Вернуть конфликт записи к строке файла после двух пропусков', ['Что проверили', 'Результат'], $rows,$checks,$runtime,$counts);
foreach ($rows as [$label,$value]) {echo $label, ' — ', $value, PHP_EOL;}

Пустая строка — 3
Ошибка до отправки — 4
Индекс в MongoDB — 1
Строка исходного CSV — 5
Артикул и код — EXIST · 11000
Вставлено остальных — 2

Открыть таблицу фактического запуска · Скачать JSON результата.

Попробуйте изменить

Вставьте ещё одну пустую строку перед EXIST. Что изменится — индекс MongoDB, номер строки CSV или оба числа?

После большой пакетной вставки оператор видит индекс и код, но не знает, какой документ отклонён. Карта индексов связывает исходный артикул и номер CSV с WriteError без разбора текста исключения. Реальная постановка на Stack Overflow. Собственная PHP-карта добавляется синхронно с BulkWrite: после исключения getIndex связывается с исходным артикулом и физической строкой. Пустые и неверные строки не перенумеровывают источник; сообщение сервера не разбирается как строковый формат.

Распознать одинаковый индекс ошибки в двух разных партиях

В большом списке оператор дважды видит «индекс 0, код 11000». На первой странице речь идёт о DUPA, на второй — о DUPB. Присвоим партии отдельный номер и сохраним исходные строки внутри каждой.

Короткий фрагмент из программы

foreach (array_chunk($validRows, 2) as $batchNumber => $entries) {
    // Для каждого массива $entries создаётся собственный BulkWrite и собственная карта.
    $receipt = q137Dispatch($manager, $ns, $entries, false);
}

Что увидит оператор

WriteError::getIndex() относится к конкретному переданному объекту BulkWrite. После создания нового объекта отсчёт начинается с нуля. Формула «номер партии × размер + индекс» найдёт в лучшем случае позицию в отфильтрованном списке, но не исходную строку, пропущенную оператором.

Границы решения

В этом примере приложение само разбивает записи по две до отправки. Внутренняя группировка драйвера по видам операций, размерам и ограничениям сервера — другой механизм. Используйте соответствие с объектом API, которому принадлежит результат.

<?php
declare(strict_types=1);
use MongoDB\Driver\{Manager,BulkWrite,WriteResult,WriteError};
use MongoDB\Driver\Exception\BulkWriteException;
require __DIR__.'/q137-helper.php';

[$rows,$checks,$runtime,$counts]=q137Lab(static function(Manager $manager,string $db,string $ns): array {
    $seed=q137Seed($manager,$ns,[['_id'=>'DUPA','qty'=>5],['_id'=>'DUPB','qty'=>6]]);
    $input="action;sku;qty\ninsert;DUPA;9\n\ninsert;OKA;1\ninsert;BAD;-1\ninsert;DUPB;9\ninsert;OKB;2";
    $parsed=q137Parse($input);
    $rows=[];$issues=[];$inserted=0;
    foreach (array_chunk($parsed['valid'],2) as $group=>$entries) {
        $receipt=q137Dispatch($manager,$ns,$entries,false);
        $problem=$receipt['issues'][0];$issues[]=$problem;
        $rows[]=['Партия '.($group+1).', индекс '.$problem['index'],'строка '.$problem['line'].' · '.$problem['sku']];
        $inserted+=$receipt['inserted'];
    }
    $accepted=q137Read($manager,$ns,['_id'=>['$in'=>['OKA','OKB']]]);
    $rows[]=['Создано товаров',$inserted];
    $rows[]=['Их артикулы',implode(', ',array_column($accepted,'_id'))];
    $checks=['two_seeded'=>$seed===2,'blank_before'=>$parsed['blanks']===[3],'bad_before'=>$parsed['invalid']===[5],
        'same_indices'=>array_column($issues,'index')===[0,0],'different_source'=>array_column($issues,'line')===[2,6],
        'both_duplicate'=>array_column($issues,'code')===[11000,11000],'both_survived'=>$inserted===2 && count($accepted)===2];
    return [$rows,$checks];
});
q137Report('mongodb137-queue-batch-offsets', 'Распознать одинаковый индекс ошибки в двух разных партиях', ['Что проверили', 'Результат'], $rows,$checks,$runtime,$counts);
foreach ($rows as [$label,$value]) {echo $label, ' — ', $value, PHP_EOL;}

Партия 1, индекс 0 — строка 2 · DUPA
Партия 2, индекс 0 — строка 6 · DUPB
Создано товаров — 2
Их артикулы — OKA, OKB

Открыть таблицу фактического запуска · Скачать JSON результата.

Попробуйте изменить

Измените размер партии с 2 на 3. Выведите все полученные ошибки в цикле вместо выбора первой. Какие две исходные строки всё равно должны быть отмечены?

Нужен массовый импорт, где дубликат одной строки допускает обработку остальных. Разбираем результат каждого отправленного пакета, исключение и проверку сохранившихся записей. Реальная постановка на Stack Overflow. Собственные два пакета PHP по две операции показывают два индекса 0, относящихся к разным физическим строкам. Частичный результат и повторное чтение подтверждают сохранение OKA/OKB. Повтор неудачных действий не объявляется автоматически безопасным.

После остановки отправить только ещё не обработанный хвост

Последовательный импорт остановился в середине на попытке создать EXIST с количеством 99. В каталоге у EXIST количество 2. Поддержке нужно продолжить независимую загрузку TAIL, оставив конфликт для отдельного решения.

Короткий фрагмент из программы

// Только для известной ошибки элемента в ordered=true.
$tail = array_slice($submitted, $writeError->getIndex() + 1);

Что увидит оператор

В этом пакете ordered=true, причина остановки — известная ошибка конкретного элемента, строки независимы друг от друга. Префикс уже выполнен. Хвост после индекса не был обработан; для него создаётся новая очередь. Существующий товар с другим количеством требует решения оператора.

Границы решения

Так нельзя восстанавливать пакет при разрыве связи или ошибке подтверждения записи. При ordered=false следующие действия тоже могли уже исполниться. При неоднозначном результате сначала сверяют известные ключи и состояние. Операции вроде $inc опасно повторять вслепую.

<?php
declare(strict_types=1);
use MongoDB\Driver\{Manager,BulkWrite,WriteResult,WriteError};
use MongoDB\Driver\Exception\BulkWriteException;
require __DIR__.'/q137-helper.php';

[$rows,$checks,$runtime,$counts]=q137Lab(static function(Manager $manager,string $db,string $ns): array {
    $seed=q137Seed($manager,$ns,[['_id'=>'EXIST','qty'=>2]]);
    $parsed=q137Parse("action;sku;qty\ninsert;NEW;1\n\ninsert;EXIST;99\ninsert;TAIL;3");
    $batch=$parsed['valid'];
    $first=q137Dispatch($manager,$ns,$batch,true);
    $error=$first['issues'][0];
    $tail=array_slice($batch,$error['index']+1);
    $existing=q137Read($manager,$ns,['_id'=>'EXIST'])[0];
    $before=q137Read($manager,$ns,['_id'=>'TAIL']);
    $resumed=q137Dispatch($manager,$ns,$tail,true);
    $after=q137Read($manager,$ns,['_id'=>'TAIL'])[0];
    $rows=[['Успели вставить до отказа',$first['inserted']],['Строка конфликта',$error['line']],['Остаток конфликтного EXIST',$existing['qty']],
        ['Строка для отдельной отправки',$tail[0]['line']],['TAIL до продолжения',count($before)],['TAIL после продолжения',$after['qty']]];
    $checks=['seed'=>$seed===1,'prefix_done'=>$first['inserted']===1,'duplicate_known'=>$error['code']===11000 && $error['index']===1,
        'conflict_not_overwritten'=>$existing['qty']===2,'tail_known'=>count($tail)===1 && $tail[0]['line']===5,
        'tail_not_yet_applied'=>$before===[],'resumed_only_tail'=>$resumed['queued']===1 && $resumed['inserted']===1 && $after['qty']===3,
        'prefix_still_intact'=>q137Read($manager,$ns,['_id'=>'NEW'])[0]['qty']===1];
    return [$rows,$checks];
});
q137Report('mongodb137-queue-resume-tail', 'После остановки отправить только ещё не обработанный хвост', ['Что проверили', 'Результат'], $rows,$checks,$runtime,$counts);
foreach ($rows as [$label,$value]) {echo $label, ' — ', $value, PHP_EOL;}

Успели вставить до отказа — 1
Строка конфликта — 4
Остаток конфликтного EXIST — 2
Строка для отдельной отправки — 5
TAIL до продолжения — 0
TAIL после продолжения — 3

Открыть таблицу фактического запуска · Скачать JSON результата.

Попробуйте изменить

Сделайте TAIL зависимым от успешного создания EXIST. Почему теперь правомерно отложить хвост целиком, даже если технически можно отправить его отдельно?

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

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

Короткий фрагмент из программы

$receipt = q137Dispatch($manager, $ns, $rowsForThisBatch, false);
foreach ($receipt['issues'] as $issue) {
    echo 'Строка ', $issue['line'], ', артикул ', $issue['sku'], ', код ', $issue['code'], PHP_EOL;
}

Что увидит оператор

KEEP сначала получил прежнее количество 3, затем новое 5. Оба фильтра совпали, но изменился товар только один раз. Строка для GHOST не создала товар, для OLD прошло удаление. На экране остаются KEEP=5 и LED=2; попытка поставить повторный LED с количеством 9 отклонена.

Границы решения

В партиях этого примера отдельные действия независимы или разведены по последовательным вызовам. unordered-пакет нельзя использовать как способ гарантировать порядок зависимых изменений одного товара. Итоговое чтение показывает текущее состояние после последовательного учебного запуска.

<?php
declare(strict_types=1);
use MongoDB\Driver\{Manager,BulkWrite,WriteResult,WriteError};
use MongoDB\Driver\Exception\BulkWriteException;
require __DIR__.'/q137-helper.php';

[$rows,$checks,$runtime,$counts]=q137Lab(static function(Manager $manager,string $db,string $ns): array {
    $seed=q137Seed($manager,$ns,[['_id'=>'KEEP','qty'=>3],['_id'=>'OLD','qty'=>1]]);
    $input="action;sku;qty\ninsert;LED;2\n\nset;BAD;-9\nset;KEEP;3\ninsert;LED;9\nset;KEEP;5\ndelete;OLD;\nset;GHOST;7";
    $parsed=q137Parse($input);
    $queued=$inserted=$matched=$changed=$deleted=0;
    $issueRows=[];$groups=0;
    foreach (array_chunk($parsed['valid'],2) as $group=>$entries) {
        $receipt=q137Dispatch($manager,$ns,$entries,false);
        $groups++;
        foreach ($receipt['issues'] as $issue) {
            $issueRows[]='партия '.($group+1).', индекс '.$issue['index'].', строка '.$issue['line'].', код '.$issue['code'];
        }
        $queued+=$receipt['queued'];$inserted+=$receipt['inserted'];$matched+=$receipt['matched'];
        $changed+=$receipt['modified'];$deleted+=$receipt['deleted'];
    }
    $actual=q137Read($manager,$ns);
    $catalog=implode(', ',array_map(fn($d)=>$d['_id'].'='.$d['qty'],$actual));
    $rows=[['Пустые строки',implode(', ',$parsed['blanks'])],['Ошибки входа',implode(', ',$parsed['invalid'])],['Отправлено операций',$queued],
        ['Ошибка MongoDB',implode(' · ',$issueRows)],['Вставлено / обновлено / удалено',$inserted.' / '.$changed.' / '.$deleted],
        ['Совпало обновлений',$matched],['Каталог после отправки',$catalog]];
    $checks=['initial_catalog'=>$seed===2,'input_rejected'=>$parsed['blanks']===[3] && $parsed['invalid']===[4],
        'three_batches'=>$groups===3 && $queued===6,'exact_issue'=>$issueRows===['партия 2, индекс 0, строка 6, код 11000'],
        'real_counters'=>$inserted===1 && $changed===1 && $deleted===1 && $matched===2,'fresh_catalog'=>$catalog==='KEEP=5, LED=2',
        'missing_stays_missing'=>q137Read($manager,$ns,['_id'=>'GHOST'])===[],'old_removed'=>q137Read($manager,$ns,['_id'=>'OLD'])===[]];
    return [$rows,$checks];
});
q137Report('mongodb137-queue-dispatch-receipt', 'Показать оператору, что из файла действительно осталось в каталоге', ['Что проверили', 'Результат'], $rows,$checks,$runtime,$counts);
foreach ($rows as [$label,$value]) {echo $label, ' — ', $value, PHP_EOL;}

Пустые строки — 3
Ошибки входа — 4
Отправлено операций — 6
Ошибка MongoDB — партия 2, индекс 0, строка 6, код 11000
Вставлено / обновлено / удалено — 1 / 1 / 1
Совпало обновлений — 2
Каталог после отправки — KEEP=5, LED=2

Открыть таблицу фактического запуска · Скачать JSON результата.

Попробуйте изменить

Поменяйте количество второго LED на исходные 2. Должен ли конфликт уникального _id исчезнуть лишь от совпадения количеств? Объясните, как оператор отличит безопасный повтор поставки от отдельной операции.

Изменить CSV в браузере и получить строковую квитанцию

В ZIP именно этого итогового примера дополнительно находятся web/import.php, web/public/index.php, web/sample.csv, web/db.php и web-README.md. Запустите php -S 127.0.0.1:8091 -t web/public и откройте адрес из инструкции. «Предпросмотр» разбирает текст без записи; «Записать» создаёт собственную пустую учебную коллекцию, выполняет импорт, перечитывает остатки и очищает коллекцию.

У формы намеренно более узкий договор: заголовок sku;qty и только вставки, количество от 1 до 9999. Это отдельная практическая ступень к смешанному CLI-импорту с action;sku;qty, а не тот же входной формат. В исходном web/sample.csv строки 2 и 5 составляют первую партию, строки 6 и 7 — вторую. Повтор LED даёт индекс 0 второй партии, но экран показывает физическую строку 6. Столбец «В каталоге, шт.» приходит из последующего запроса, а не копируется из входа. Исправьте второй LED на PIN: должны сохраниться четыре допустимые строки. Детали запуска находятся в web-README.md.

Четыре карточки: очередь, счётчик, результат и ошибка

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

Применить квитанцию в своём импорте

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

Если одно поручение затрагивает товар и связанную запись другой коллекции, переходите к отправке изменений по нескольким коллекциям. Для выбора уровня подтверждения — к read/write concern, для безопасного изменения остатка — к условной атомарной записи. Эти четыре карточки закрывают перечисленные узлы справочника; они не заменяют всё дерево MongoDB.