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

От задания на запись к результату сервера

Импорт или служебная операция часто меняет несколько объектов: карточку товара, остаток, черновик заказа. BulkWriteCommand позволяет подготовить список вставок, изменений и удалений, указав коллекцию для каждой операции, затем выполнить его через Manager. Сначала разберём одну вставку; после этого — связанные адреса и реальные границы пакетной записи.

$bulk = new MongoDB\Driver\BulkWriteCommand;
$id = $bulk->insertOne($catalogNamespace, ['_id'=>'PEN-7','stock'=>4]);
$result = $manager->executeBulkWriteCommand($bulk);

$bulk — переменная с очередью операций. new создаёт объект; -> вызывает его метод. Первый аргумент insertOne — разрешённый адрес коллекции, второй — документ с полями. Результат $id известен до отправки; $result появляется после execute. В полном примере ниже есть создание Manager, коллекции и проверка результата, поэтому фрагмент не требует угадывать подготовку.

Строка namespace в MongoDB имеет форму база.коллекция, например php_manual_lab.catalog: это адрес коллекции внутри сервера базы данных. Она не равна PHP namespace MongoDB\Driver и не является объектом MongoDB\Collection библиотеки Composer. Мы используем низкоуровневое расширение, Composer не нужен. Основы соединения и документа: операции драйвера; смысл BSON-типов: ID, дата и цена.

Пакет, одна коллекция и транзакция

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

Как запустить и увидеть изменения

Во всех восьми архивах находятся example.php, mw121-helper.php и README.txt. Требования упражнения: PHP 8.4+ CLI x64, mongodb 2.5+, локальный MongoDB 8.0+. Проверяемая среда — PHP 8.5.11 / расширение 2.5.5 / сервер 8.0.34. Все примеры действительно записывают и читают свои коллекции; синтаксическая проверка не подменяет запуск.

README содержит установку расширения/сервера, отдельный учебный dbpath, bind_ip=127.0.0.1, порт27075 и переменные PHPMAN_MONGODB_URI/PHPMAN_MONGODB_DATABASE. Используется отдельная база php_manual_lab. Адреса не получаются из формы; helper допускает только явно указанный loopback и учебное имя базы.

Коллекции получают случайный суффикс; владение отмечается после успешного create. finally удаляет только точные созданные имена, затем listCollections подтверждает отсутствие. Нет dropDatabase, отключения проверки схемы или изменений сервера. Для просмотра остаются result.html/result.json, а metrics.json хранит версии, проверки и хеши. Аварийное убийство процесса не гарантирует finally.

Запустите php example.php в распакованном каталоге и откройте result.html. Чтение ограничено проекцией, устойчивой сортировкой и limit=20; все учебные наборы меньше лимита. На сайте открывается сохранённый результат выполненной программы, а не запрос к вашей базе.

Подготовить записи и только затем отправить

Импорт получил две товарные строки. Нужно подготовить задания, проверить их количество, затем отправить в MongoDB. Полученный от insertOne ID ещё не доказывает, что сервер принял товар.

Исходные данные

PEN-7 имеет строковый _id и остаток 4. Для PEN-8 указан только sku и остаток 6; драйвер создаст ObjectId. Обе записи идут в собственную новую коллекцию.

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

$bulk = new MongoDB\Driver\BulkWriteCommand;
$id = $bulk->insertOne($catalogNamespace, ['_id'=>'PEN-7','stock'=>4]);
echo count($bulk); // 1: queued, not yet written

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

Что получится после выполнения

Почему именно такой результат

BulkWriteCommand — объект очереди, не соединение и не коллекция. insertOne добавляет задание «вставить один документ». До execute можно получить _id, но запись находится только в подготовленном пакете.

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

count($bulk) вызывает Countable::count и даёт число добавленных операций. После отправки отдельно проверяются getInsertedCount и реальные поля из базы. Чтение использует projection, sort по sku и limit=20: это просмотр маленькой фикстуры, не выгрузка рабочего каталога.

Границы применения

Драйвер не проверяет смысл артикула и не делает sku уникальным без соответствующего индекса. ObjectId не заменяет бизнес-номер товара. Подготовка пакета не является транзакцией.

<?php
declare(strict_types=1);
require __DIR__.'/mw121-helper.php';
[$manager,$database,$runtime]=mw121Connect();
$owned=[];$details=[];
try{
$ns=mw121Create($manager,$database,['catalog'],$owned);
$bulk=new MongoDB\Driver\BulkWriteCommand;
$empty=count($bulk);
$firstId=$bulk->insertOne($ns['catalog'],['_id'=>'PEN-7','sku'=>'PEN-7','stock'=>4]);
$generatedId=$bulk->insertOne($ns['catalog'],['sku'=>'PEN-8','stock'=>6]);
$queued=$bulk->count();
$before=mw121Read($manager,$ns['catalog'],[],['_id'=>0,'sku'=>1],['sku'=>1]);
$result=mw121Run($manager,$bulk);
$after=mw121Read($manager,$ns['catalog'],[],['sku'=>1,'stock'=>1],['sku'=>1]);
$rows=[['До добавления операций',$empty],['В очереди',$queued],['В базе до execute',count($before)],
    ['Вставлено сервером',$result->getInsertedCount()],['PEN-7: остаток',$after[0]['stock']],
    ['PEN-8: остаток',$after[1]['stock']],['Тип автоматически созданного ID',get_debug_type($generatedId)]];
$checks=['queue_is_not_database'=>$empty===0 && $queued===2 && $before===[],
    'inserted_two'=>$result->getInsertedCount()===2 && count($after)===2,
    'explicit_id'=>$firstId==='PEN-7' && $after[0]['_id']==='PEN-7',
    'generated_id'=>$generatedId instanceof MongoDB\BSON\ObjectId && (string)$after[1]['_id']===(string)$generatedId,
    'stock_values'=>array_column($after,'stock')===[4,6]];
}finally{
    foreach(array_reverse($owned) as $collection){mw121Command($manager,$database,['drop'=>$collection],true);}
}
$removed=true;
foreach($owned as $collection){if(mw121Exists($manager,$database,$collection)){$removed=false;}}
$checks['owned_collections_removed']=$removed;
mw121Report('mongodb121-multi-queue-insert', ['Наблюдение', 'Результат'], $rows, $checks, $runtime, $details);
echo 'mongodb121-multi-queue-insert: saved result.html and result.json
';

mongodb121-multi-queue-insert: saved result.html and result.json

Открыть фактический HTML результата · Скачать JSON таблицы

Упражнение с ориентиром результата. Добавьте третий товар с остатком 0. До execute коллекция остаётся пустой; count станет 3, а после успеха getInsertedCount — 3.

Собрать каталог, остаток и черновик заказа

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

Исходные данные

Каталог PEN-7: «Ручка». Склад WH1:PEN-7: stock=10. ORDER-1 ссылается на PEN-7, qty=2, status=draft. Это черновик, не резервирование.

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

$bulk->insertOne($catalogNamespace, ['_id'=>'PEN-7','name'=>'Ручка']);
$bulk->insertOne($ordersNamespace, ['_id'=>'ORDER-1','sku'=>'PEN-7','status'=>'draft']);

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

Что получится после выполнения

Почему именно такой результат

Namespace здесь — строка database.collection. База задаётся окружением, имена коллекций получаются после создания своих фикстур. Это не PHP namespace MongoDB\Driver: обратная косая черта относится к имени PHP-класса, точка — к адресу MongoDB.

Каждая операция получает свой адрес. Поэтому один BulkWriteCommand охватывает несколько коллекций. У прежнего BulkWrite все операции относятся к одной коллекции, указанной при executeBulkWrite.

ordered=true сохраняет последовательность, но не откатывает ранний успех при поздней ошибке. Черновик намеренно не объявляется оплаченным или зарезервированным: stock остаётся10. Общий sku связывает записи по смыслу; внешний ключ автоматически не создаётся.

Границы применения

Не берите database.collection напрямую из формы. Выбирайте разрешённые коллекции на сервере. Междокументное оформление заказа с общим all-or-none требует отдельного решения, часто транзакции.

<?php
declare(strict_types=1);
require __DIR__.'/mw121-helper.php';
[$manager,$database,$runtime]=mw121Connect();
$owned=[];$details=[];
try{
$ns=mw121Create($manager,$database,['catalog', 'stocks', 'orders'],$owned);
$bulk=new MongoDB\Driver\BulkWriteCommand(['ordered'=>true,'comment'=>'php-manual catalog draft']);
$bulk->insertOne($ns['catalog'],['_id'=>'PEN-7','name'=>'Ручка']);
$bulk->insertOne($ns['stocks'],['_id'=>'WH1:PEN-7','sku'=>'PEN-7','stock'=>10]);
$bulk->insertOne($ns['orders'],['_id'=>'ORDER-1','sku'=>'PEN-7','qty'=>2,'status'=>'draft']);
$result=mw121Run($manager,$bulk);
$catalog=mw121Read($manager,$ns['catalog'],['_id'=>'PEN-7'],['name'=>1]);
$stock=mw121Read($manager,$ns['stocks'],['_id'=>'WH1:PEN-7'],['sku'=>1,'stock'=>1]);
$order=mw121Read($manager,$ns['orders'],['_id'=>'ORDER-1'],['sku'=>1,'qty'=>1,'status'=>1]);
$rows=[['Каталог',$catalog[0]['_id'],$catalog[0]['name']],['Склад',$stock[0]['sku'],(string)$stock[0]['stock']],
    ['Черновик',$order[0]['_id'],$order[0]['status']],['Операций / вставок',(string)count($bulk),(string)$result->getInsertedCount()]];
$checks=['three_namespaces'=>count(array_unique(array_values($ns)))===3,
    'three_inserts'=>count($bulk)===3 && $result->getInsertedCount()===3,
    'related_values'=>$catalog[0]['_id']===$stock[0]['sku'] && $stock[0]['sku']===$order[0]['sku'],
    'draft_not_reservation'=>$stock[0]['stock']===10 && $order[0]['status']==='draft' && $order[0]['qty']===2];
}finally{
    foreach(array_reverse($owned) as $collection){mw121Command($manager,$database,['drop'=>$collection],true);}
}
$removed=true;
foreach($owned as $collection){if(mw121Exists($manager,$database,$collection)){$removed=false;}}
$checks['owned_collections_removed']=$removed;
mw121Report('mongodb121-multi-multi-collections', ['Коллекция / итог', 'Ключ', 'Значение'], $rows, $checks, $runtime, $details);
echo 'mongodb121-multi-multi-collections: saved result.html and result.json
';

mongodb121-multi-multi-collections: saved result.html and result.json

Открыть фактический HTML результата · Скачать JSON таблицы

Упражнение с ориентиром результата. Добавьте source="import" только в черновик. Не уменьшайте stock. Отдельно определите реакцию на частичный успех до превращения пакета в оформление заказа.

Условно изменить остаток и выбрать одну заявку

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

Исходные данные

PEN-7: stock=5. Последовательно запрашиваем2 и9. Заявки10/11: draft, priority=1; заявка12: paid. Sort priority DESC, _id ASC выбирает10.

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

$bulk->updateOne($stocksNamespace, ['_id'=>'PEN-7','stock'=>['$gte'=>2]], ['$inc'=>['stock'=>-2]]);

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

Что получится после выполнения

Почему именно такой результат

Фильтр updateOne включает бизнес-ключ и условие текущего остатка. Проверка условия и изменение одного документа атомарны. Не нужно сначала загружать stock в PHP и затем безусловно записывать уменьшенное значение.

Ноль совпадений — нормальный результат, не write error. Вторая операция ничего не списывает и не останавливает пакет. Нельзя следом безусловно подтверждать заказ в надежде, что ordered остановится при нехватке товара.

sort выбирает одну из нескольких подходящих заявок. При равном priority дополнительный _id даёт определённый порядок. Три задания дают два matched и два modified; таблица показывает и количество задач, и фактическое состояние.

Границы применения

Два независимых изменения разных коллекций не становятся атомарным резервом заказа. Для конкретно выбранного пользователем объекта предпочтителен уникальный ключ в фильтре.

<?php
declare(strict_types=1);
require __DIR__.'/mw121-helper.php';
[$manager,$database,$runtime]=mw121Connect();
$owned=[];$details=[];
try{
$ns=mw121Create($manager,$database,['stocks', 'orders'],$owned);
mw121Seed($manager,$ns['stocks'],[['_id'=>'PEN-7','stock'=>5]]);
mw121Seed($manager,$ns['orders'],[['_id'=>10,'status'=>'draft','priority'=>1],['_id'=>11,'status'=>'draft','priority'=>1],['_id'=>12,'status'=>'paid','priority'=>5]]);
$bulk=new MongoDB\Driver\BulkWriteCommand;
$bulk->updateOne($ns['stocks'],['_id'=>'PEN-7','stock'=>['$gte'=>2]],['$inc'=>['stock'=>-2]]);
$bulk->updateOne($ns['stocks'],['_id'=>'PEN-7','stock'=>['$gte'=>9]],['$inc'=>['stock'=>-9]]);
$bulk->updateOne($ns['orders'],['status'=>'draft'],['$set'=>['status'=>'review']],['sort'=>['priority'=>-1,'_id'=>1]]);
$result=mw121Run($manager,$bulk);
$stock=mw121Read($manager,$ns['stocks'],['_id'=>'PEN-7'],['stock'=>1])[0];
$orders=mw121Read($manager,$ns['orders'],[],['status'=>1]);
$rows=[['Остаток PEN-7',(string)$stock['stock']],['Заявка 10',$orders[0]['status']],['Заявка 11',$orders[1]['status']],
    ['Заявка 12',$orders[2]['status']],['Операций', (string)count($bulk)],['Совпавших документов',(string)$result->getMatchedCount()]];
$checks=['conditional_stock'=>$stock['stock']===3,'stable_first'=>array_column($orders,'status')===['review','draft','paid'],
    'not_match_is_not_error'=>$result->getMatchedCount()===2 && $result->getModifiedCount()===2 && count($bulk)===3];
}finally{
    foreach(array_reverse($owned) as $collection){mw121Command($manager,$database,['drop'=>$collection],true);}
}
$removed=true;
foreach($owned as $collection){if(mw121Exists($manager,$database,$collection)){$removed=false;}}
$checks['owned_collections_removed']=$removed;
mw121Report('mongodb121-multi-reserve-first', ['Наблюдение', 'Значение'], $rows, $checks, $runtime, $details);
echo 'mongodb121-multi-reserve-first: saved result.html and result.json
';

mongodb121-multi-reserve-first: saved result.html and result.json

Открыть фактический HTML результата · Скачать JSON таблицы

Упражнение с ориентиром результата. Дайте заявке11 priority=3: первой станет она. После первого списания запросите4 — остаток3 не изменится, исключения не будет.

Практическая проблема: mongoose bulkwrite upsert only works with creation, not updating. Фильтр обновления может подходить нескольким документам, а разработчик смотрит результат у другого. Сценарий явно связывает фильтр, уникальный идентификатор либо устойчивый sort и реально выбранную запись. Это постановка проблемы, а не утверждение о точной причине чужого исторического сбоя. Обсуждение задаёт вопрос; актуальные правила взяты из первичных источников, код и данные оригинальные.

Обновить группы товаров и черновиков

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

Исходные данные

Два товара pen и один book; два заказа draft и один paid. Группы независимы и находятся в разных собственных коллекциях.

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

$bulk->updateMany($catalogNamespace, ['category'=>'pen'], ['$set'=>['active'=>false]]);

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

Что получится после выполнения

Почему именно такой результат

updateMany меняет все совпадения одного серверного фильтра. Одна операция здесь затрагивает два документа. count пакета нельзя использовать как количество документов или прогноз размера результата.

$set меняет перечисленные поля и оставляет остальные. MongoDB выполняет отбор; PHP читает только небольшую проекцию для показа результата. В рабочей базе такой фильтр нуждается в подходящем индексе.

ordered=false подходит независимым группам. Он не гарантирует ускорение или параллельность, не убирает ошибки и не создаёт общий откат. Атомарность updateMany относится к каждому документу, а не ко всей группе сразу.

Границы применения

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

<?php
declare(strict_types=1);
require __DIR__.'/mw121-helper.php';
[$manager,$database,$runtime]=mw121Connect();
$owned=[];$details=[];
try{
$ns=mw121Create($manager,$database,['catalog', 'orders'],$owned);
mw121Seed($manager,$ns['catalog'],[['_id'=>1,'category'=>'pen','active'=>true],['_id'=>2,'category'=>'pen','active'=>true],['_id'=>3,'category'=>'book','active'=>true]]);
mw121Seed($manager,$ns['orders'],[['_id'=>10,'status'=>'draft'],['_id'=>11,'status'=>'draft'],['_id'=>12,'status'=>'paid']]);
$bulk=new MongoDB\Driver\BulkWriteCommand(['ordered'=>false]);
$bulk->updateMany($ns['catalog'],['category'=>'pen'],['$set'=>['active'=>false]]);
$bulk->updateMany($ns['orders'],['status'=>'draft'],['$set'=>['status'=>'cancelled']]);
$result=mw121Run($manager,$bulk);
$catalog=mw121Read($manager,$ns['catalog'],[],['active'=>1]);$orders=mw121Read($manager,$ns['orders'],[],['status'=>1]);
$rows=[];foreach($catalog as $item){$rows[]=['Товар',(string)$item['_id'],$item['active']?'активен':'скрыт'];}
foreach($orders as $order){$rows[]=['Заказ',(string)$order['_id'],$order['status']];}
$rows[]=['Итог','Операций / изменённых документов',count($bulk).' / '.$result->getModifiedCount()];
$checks=['catalog_group'=>array_column($catalog,'active')===[false,false,true],
    'orders_group'=>array_column($orders,'status')===['cancelled','cancelled','paid'],
    'two_operations_four_changes'=>count($bulk)===2 && $result->getMatchedCount()===4 && $result->getModifiedCount()===4];
}finally{
    foreach(array_reverse($owned) as $collection){mw121Command($manager,$database,['drop'=>$collection],true);}
}
$removed=true;
foreach($owned as $collection){if(mw121Exists($manager,$database,$collection)){$removed=false;}}
$checks['owned_collections_removed']=$removed;
mw121Report('mongodb121-multi-batch-maintenance', ['Тип', 'ID / показатель', 'Результат'], $rows, $checks, $runtime, $details);
echo 'mongodb121-multi-batch-maintenance: saved result.html and result.json
';

mongodb121-multi-batch-maintenance: saved result.html and result.json

Открыть фактический HTML результата · Скачать JSON таблицы

Упражнение с ориентиром результата. Добавьте ещё один book и paid. Modified останется4. При повторе новым пакетом draft уже не найдутся, а скрытые pen могут совпасть, но не измениться.

Полностью заменить снимки и создать отсутствующий

Интеграция передаёт полный снимок товара и адреса. Старые поля, отсутствующие в снимке, должны исчезнуть: это замена документа, а не частичная правка.

Исходные данные

Товар1: цена100 и legacy_note; новый снимок: цена150 без заметки. Адрес9 меняется на Тулу/Новую без note. Отсутствующий товар2 создаётся с upsert=true.

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

$bulk->replaceOne($catalogNamespace, ['_id'=>1], ['name'=>'Ручка','price_kopecks'=>150]);

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

Что получится после выполнения

Почему именно такой результат

replacement — новый документ целиком, без операторов $set/$inc. Непереданные старые поля исчезают. Поэтому replaceOne не подходит частичной форме, приславшей только name, если остальные данные нужно сохранить.

_id существующего документа сохраняется, если replacement его не задаёт; изменить имеющийся _id нельзя. Для нового товара ID передан явно. Upsert выключен по умолчанию; только третья операция создаёт документ при отсутствии совпадения.

Вставка replaceOne с upsert строится из replacement. Таблица проверяет и новые значения, и исчезновение legacy_note/note; одного matchedCount недостаточно для проверки правильной формы.

Границы применения

Источник полного снимка должен иметь право заменить все эти поля. Не стирайте owner/audit по ошибке. При конкурентном редактировании нужен фильтр версии или иное согласование.

<?php
declare(strict_types=1);
require __DIR__.'/mw121-helper.php';
[$manager,$database,$runtime]=mw121Connect();
$owned=[];$details=[];
try{
$ns=mw121Create($manager,$database,['catalog', 'addresses'],$owned);
mw121Seed($manager,$ns['catalog'],[['_id'=>1,'name'=>'Старое имя','legacy_note'=>'remove','price_kopecks'=>100]]);
mw121Seed($manager,$ns['addresses'],[['_id'=>9,'city'=>'Москва','street'=>'Старая','note'=>'remove']]);
$bulk=new MongoDB\Driver\BulkWriteCommand;
$bulk->replaceOne($ns['catalog'],['_id'=>1],['name'=>'Ручка','price_kopecks'=>150]);
$bulk->replaceOne($ns['addresses'],['_id'=>9],['city'=>'Тула','street'=>'Новая']);
$bulk->replaceOne($ns['catalog'],['_id'=>2],['_id'=>2,'name'=>'Блокнот','price_kopecks'=>350],['upsert'=>true]);
$result=mw121Run($manager,$bulk);
$catalog=mw121Read($manager,$ns['catalog'],[],['name'=>1,'price_kopecks'=>1,'legacy_note'=>1]);
$address=mw121Read($manager,$ns['addresses'],['_id'=>9],['city'=>1,'street'=>1,'note'=>1])[0];
$rows=[['Товар 1',$catalog[0]['name'],(string)$catalog[0]['price_kopecks']],['Товар 2',$catalog[1]['name'],(string)$catalog[1]['price_kopecks']],
    ['Адрес 9',$address['city'],$address['street']],['Старые поля','legacy_note / note',(!isset($catalog[0]['legacy_note'],$address['note']) && !array_key_exists('legacy_note',$catalog[0]) && !array_key_exists('note',$address))?'удалены':'остались'],
    ['Итог','Изменено / добавлено upsert',$result->getModifiedCount().' / '.$result->getUpsertedCount()]];
$checks=['replacement_removed_old_fields'=>!array_key_exists('legacy_note',$catalog[0]) && !array_key_exists('note',$address),
    'ids_retained'=>$catalog[0]['_id']===1 && $address['_id']===9,
    'values'=>array_column($catalog,'price_kopecks')===[150,350] && $address['city']==='Тула',
    'upsert_only_missing'=>$result->getMatchedCount()===2 && $result->getModifiedCount()===2 && $result->getUpsertedCount()===1];
}finally{
    foreach(array_reverse($owned) as $collection){mw121Command($manager,$database,['drop'=>$collection],true);}
}
$removed=true;
foreach($owned as $collection){if(mw121Exists($manager,$database,$collection)){$removed=false;}}
$checks['owned_collections_removed']=$removed;
mw121Report('mongodb121-multi-replace-snapshots', ['Объект', 'Поле / значение', 'Результат'], $rows, $checks, $runtime, $details);
echo 'mongodb121-multi-replace-snapshots: saved result.html and result.json
';

mongodb121-multi-replace-snapshots: saved result.html and result.json

Открыть фактический HTML результата · Скачать JSON таблицы

Упражнение с ориентиром результата. Добавьте apartment только в старый адрес: после замены он исчезнет. Если это неправильно для вашей формы, используйте updateOne и $set изменённых полей.

Практическая проблема: Not able to update mongo collection using Bulkwrite. Операция, задуманная как изменение существующей записи, собрана как вставка и встречает ограничение уникальности. В учебном решении сначала выбирается смысл insert/update/replace, а затем проверяется получившийся документ; индекс не удаляется ради обхода ошибки. Обсуждение задаёт вопрос; актуальные правила взяты из первичных источников, код и данные оригинальные.

Удалить выбранную запись и группы по фильтру

Нужно удалить выбранный отменённый заказ, тестовый товар, все ненужные черновики и просроченный журнал, сохранив оплаченные заказы и свежие записи.

Исходные данные

Заказы1 cancelled,2/3 draft,4 paid; товары7 sample=true,8 sample=false; журнал1/2 expired=true,3 expired=false. Всё это новые собственные фикстуры.

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

$bulk->deleteOne($ordersNamespace, ['_id'=>1,'status'=>'cancelled']);
$bulk->deleteMany($logsNamespace, ['expired'=>true]);

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

Что получится после выполнения

Почему именно такой результат

deleteOne ограничивает удаление единицей, но широкий фильтр не гарантирует выбор нужного пользователю объекта. Здесь _id и состояние однозначно задают запись. Пустой фильтр такой защиты не имеет.

deleteMany удаляет всю подходящую группу своей коллекции. Namespace отделяет журнал от заказов; filter выбирает группу внутри. В многопользовательском сервисе фильтр также ограничивают tenant/owner.

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

Границы применения

Удаление требует отдельно предусмотренной истории или резервного восстановления. Демонстрация ограничена своими учебными коллекциями; окончательная уборка finally использует только их точные имена.

<?php
declare(strict_types=1);
require __DIR__.'/mw121-helper.php';
[$manager,$database,$runtime]=mw121Connect();
$owned=[];$details=[];
try{
$ns=mw121Create($manager,$database,['orders', 'catalog', 'logs'],$owned);
mw121Seed($manager,$ns['orders'],[['_id'=>1,'status'=>'cancelled'],['_id'=>2,'status'=>'draft'],['_id'=>3,'status'=>'draft'],['_id'=>4,'status'=>'paid']]);
mw121Seed($manager,$ns['catalog'],[['_id'=>7,'sample'=>true],['_id'=>8,'sample'=>false]]);
mw121Seed($manager,$ns['logs'],[['_id'=>1,'expired'=>true],['_id'=>2,'expired'=>true],['_id'=>3,'expired'=>false]]);
$bulk=new MongoDB\Driver\BulkWriteCommand;
$bulk->deleteOne($ns['orders'],['_id'=>1,'status'=>'cancelled']);
$bulk->deleteOne($ns['catalog'],['_id'=>7,'sample'=>true]);
$bulk->deleteMany($ns['orders'],['status'=>'draft']);
$bulk->deleteMany($ns['logs'],['expired'=>true]);
$result=mw121Run($manager,$bulk);
$orders=mw121Read($manager,$ns['orders'],[],['_id'=>1,'status'=>1]);
$catalog=mw121Read($manager,$ns['catalog'],[],['_id'=>1]);$logs=mw121Read($manager,$ns['logs'],[],['_id'=>1]);
$rows=[['Заказы',implode(',',array_column($orders,'_id'))],['Каталог',implode(',',array_column($catalog,'_id'))],
    ['Журнал',implode(',',array_column($logs,'_id'))],['Операций',(string)count($bulk)],['Удалённых документов',(string)$result->getDeletedCount()]];
$checks=['paid_order_retained'=>$orders===[['_id'=>4,'status'=>'paid']],
    'non_sample_retained'=>array_column($catalog,'_id')===[8],'fresh_log_retained'=>array_column($logs,'_id')===[3],
    'four_operations_six_deletes'=>count($bulk)===4 && $result->getDeletedCount()===6];
}finally{
    foreach(array_reverse($owned) as $collection){mw121Command($manager,$database,['drop'=>$collection],true);}
}
$removed=true;
foreach($owned as $collection){if(mw121Exists($manager,$database,$collection)){$removed=false;}}
$checks['owned_collections_removed']=$removed;
mw121Report('mongodb121-multi-cleanup-selection', ['Коллекция / показатель', 'Остались ID / значение'], $rows, $checks, $runtime, $details);
echo 'mongodb121-multi-cleanup-selection: saved result.html and result.json
';

mongodb121-multi-cleanup-selection: saved result.html and result.json

Открыть фактический HTML результата · Скачать JSON таблицы

Упражнение с ориентиром результата. Добавьте paid5 и свежий журнал4. Они должны остаться, а deletedCount по-прежнему будет6.

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

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

Исходные данные

Перед каждым вариантом существует ID100. Пакет добавляет новый ID1, конфликтующий ID100 и независимый маркер журнала8. Заранее созданный конфликт не зависит от порядка unordered.

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

$bulk = new MongoDB\Driver\BulkWriteCommand(['ordered'=>false]);
// Independent writes continue, but execute still reports a duplicate-key error.

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

Что получится после выполнения

Почему именно такой результат

ordered=true останавливается после первой ошибки, но не откатывает уже успешную вставку. Реальное чтение после исключения подтверждает присутствие товара1.

ordered=false допускает произвольный порядок. Фикстура не зависит от него:100 занят заранее,1 и8 независимы. Мы не утверждаем, что сервер исполнял их параллельно.

Только BulkWriteCommandException с единственной WriteError по индексу1 и кодом11000 считается ожидаемым конфликтом. Иной сбой пробрасывается дальше. Маркер означает независимую попытку импорта, а не успешность всех строк.

Границы применения

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

<?php
declare(strict_types=1);
require __DIR__.'/mw121-helper.php';
[$manager,$database,$runtime]=mw121Connect();
$owned=[];$details=[];
try{
$ns=mw121Create($manager,$database,['catalog_ordered', 'audit_ordered', 'catalog_unordered', 'audit_unordered'],$owned);
$rows=[];$checks=[];
foreach([true,false] as $ordered){
    $mode=$ordered?'ordered':'unordered';$catalogNamespace=$ns['catalog_'.$mode];$auditNamespace=$ns['audit_'.$mode];
    mw121Seed($manager,$catalogNamespace,[['_id'=>100,'name'=>'Уже существует']]);
    $bulk=new MongoDB\Driver\BulkWriteCommand(['ordered'=>$ordered]);
    $bulk->insertOne($catalogNamespace,['_id'=>1,'name'=>'Новый товар']);
    $bulk->insertOne($catalogNamespace,['_id'=>100,'name'=>'Конфликт']);
    $bulk->insertOne($auditNamespace,['_id'=>8,'event'=>'independent import marker']);
    $caught=false;
    try{mw121Run($manager,$bulk);}catch(MongoDB\Driver\Exception\BulkWriteCommandException $error){
        $writeErrors=$error->getWriteErrors();
        if(array_keys($writeErrors)!==[1] || $writeErrors[1]->getCode()!==11000){throw $error;}
        $caught=true;
    }
    $catalog=mw121Read($manager,$catalogNamespace,[],['_id'=>1]);
    $audit=mw121Read($manager,$auditNamespace,[],['_id'=>1]);
    $rows[]=[$mode,implode(',',array_column($catalog,'_id')),implode(',',array_column($audit,'_id'))?:'нет',$caught?'да':'нет'];
    $checks[$mode.'_reported_error']=$caught;
    $checks[$mode.'_no_rollback']=array_column($catalog,'_id')===[1,100];
    $checks[$mode.'_continuation']=array_column($audit,'_id')===($ordered?[]:[8]);
}
}finally{
    foreach(array_reverse($owned) as $collection){mw121Command($manager,$database,['drop'=>$collection],true);}
}
$removed=true;
foreach($owned as $collection){if(mw121Exists($manager,$database,$collection)){$removed=false;}}
$checks['owned_collections_removed']=$removed;
mw121Report('mongodb121-multi-ordered-boundary', ['Режим', 'ID каталога после ошибки', 'ID независимого журнала', 'Исключение'], $rows, $checks, $runtime, $details);
echo 'mongodb121-multi-ordered-boundary: saved result.html and result.json
';

mongodb121-multi-ordered-boundary: saved result.html and result.json

Открыть фактический HTML результата · Скачать JSON таблицы

Упражнение с ориентиром результата. Замените конфликт100 на свободный101: обе группы должны записать всё без исключения. Объясните, почему unordered нельзя применять к зависимым «сначала вставь, затем обнови эту запись».

Практическая проблема: Mongodb bulk insert ordered behaviour. При ordered=false читатель ожидает отсутствие исключения, хотя отдельная вставка с повторным ключом всё равно ошибочна. Разбор показывает продолжившиеся независимые записи и отдельно саму ошибку, без обещания отката успешных операций. Обсуждение задаёт вопрос; актуальные правила взяты из первичных источников, код и данные оригинальные.

Не отправлять пустой пакет и не выполнять объект повторно

Импорт иногда получает пустую партию или повторно отправляет уже выполненный объект. Нужно различать отсутствие задачи, одноразовый пакет и новую независимую задачу.

Исходные данные

Пустой объект; отдельный пакет вставки ORDER-2/draft; попытка повторить тот же объект; новый пакет условного перехода draft→review.

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

if (count($bulk) > 0) {
    $result = $manager->executeBulkWriteCommand($bulk);
}
// Create a new BulkWriteCommand for the next independent task.

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

Что получится после выполнения

Почему именно такой результат

executeBulkWriteCommand требует хотя бы одну операцию. Обычно пустую партию пропускают по count; здесь вызов сделан намеренно, чтобы увидеть документированную ошибку.

Тот же объект нельзя выполнить повторно. Это ограничение жизненного цикла, не защита бизнес-задачи от дублей: новый объект с прежними операциями всё ещё может повторить эффект.

Новый пакет выполняет другую задачу — условную смену статуса, а не повтор insert. Обе ожидаемые ошибки ловятся как InvalidArgumentException; состояние после них подтверждает ровно одну вставку и review.

Границы применения

Проверка count не проверяет фильтры, права или идемпотентность. Создание нового объекта не отменяет необходимости разобрать частичный или неопределённый предыдущий результат.

<?php
declare(strict_types=1);
require __DIR__.'/mw121-helper.php';
[$manager,$database,$runtime]=mw121Connect();
$owned=[];$details=[];
try{
$ns=mw121Create($manager,$database,['orders'],$owned);
$empty=new MongoDB\Driver\BulkWriteCommand;$emptyRejected=false;
try{mw121Run($manager,$empty);}catch(MongoDB\Driver\Exception\InvalidArgumentException $error){$emptyRejected=true;}
$bulk=new MongoDB\Driver\BulkWriteCommand;
$bulk->insertOne($ns['orders'],['_id'=>'ORDER-2','status'=>'draft']);
$first=mw121Run($manager,$bulk);
$reuseRejected=false;
try{mw121Run($manager,$bulk);}catch(MongoDB\Driver\Exception\InvalidArgumentException $error){$reuseRejected=true;}
$next=new MongoDB\Driver\BulkWriteCommand;
$next->updateOne($ns['orders'],['_id'=>'ORDER-2','status'=>'draft'],['$set'=>['status'=>'review']]);
$second=mw121Run($manager,$next);
$orders=mw121Read($manager,$ns['orders'],['_id'=>'ORDER-2'],['status'=>1]);
$rows=[['Пустой объект отклонён',$emptyRejected?'да':'нет'],['Первый пакет вставил',(string)$first->getInsertedCount()],
    ['Повтор того же объекта отклонён',$reuseRejected?'да':'нет'],['Новый пакет изменил',(string)$second->getModifiedCount()],
    ['Заказ ORDER-2',$orders[0]['status']]];
$checks=['empty_rejected'=>$emptyRejected,'reuse_rejected'=>$reuseRejected,
    'single_insert'=>$first->getInsertedCount()===1 && count($orders)===1,
    'new_object_works'=>$second->getModifiedCount()===1 && $orders[0]['status']==='review'];
}finally{
    foreach(array_reverse($owned) as $collection){mw121Command($manager,$database,['drop'=>$collection],true);}
}
$removed=true;
foreach($owned as $collection){if(mw121Exists($manager,$database,$collection)){$removed=false;}}
$checks['owned_collections_removed']=$removed;
mw121Report('mongodb121-multi-lifecycle', ['Действие', 'Результат'], $rows, $checks, $runtime, $details);
echo 'mongodb121-multi-lifecycle: saved result.html and result.json
';

mongodb121-multi-lifecycle: saved result.html and result.json

Открыть фактический HTML результата · Скачать JSON таблицы

Упражнение с ориентиром результата. Обработайте две партии, одна пустая. Создавайте объект для каждой и отправляйте только при count>0. Непустая партия должна быть выполнена один раз.

Где задаются опции и что они меняют

Общие опции задаются конструктору пакета, параметры конкретной операции — соответствующему методу, session/writeConcern — execute. Не переносите названия аргументов между слоями.

В документации let помечен как серверная возможность MongoDB 5.0+, collation — 3.4+. Для самого BulkWriteCommand всё равно нужен сервер 8.0+: эти исторические пометки не делают новый класс совместимым со старым сервером.

Опции операций перечислены в каждой карточке полностью. Collation требует locale; остальные поля collation зависят от нужного сравнения. Hint не создаёт индекс. Let использует постоянные выражения и доступ $$имя в выражении; это не интерполяция строки SQL и не PHP-переменная.

Для update можно передать документ операторов или поддерживаемый pipeline: $set/$addFields, $project/$unset, $replaceRoot/$replaceWith. Это не любой pipeline чтения; arrayFilters не применяется к pipeline update. Неподходящая схема обновления должна быть исправлена, а не скрыта bypassDocumentValidation.

Упражнения не демонстрируют каждую комбинацию опций как отдельный серверный запуск. Справочник сохраняет полный перечень текущих страниц API; новые собственные кейсы проверки схемы, collation, массивов и индексов дополняют этот материал по соответствующим темам.

Все методы подготовки и выполнения пакета

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

Проверить смысл операции, затем её результат

Выберите нужное действие по смыслу: insert для нового документа, update для изменений, replace для полного снимка, delete для явно ограниченной области. Затем отдельно решите, какие операции независимы, как проверяется результат и что делать при частичном успехе.

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