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

Узнать источник ответа и не путать его с настройками

Товар пришёл из MongoDB, но для разбора проблемы нужно понять: какой узел ответил, какие настройки использовал клиент и что именно означает isPrimary=false. Научимся получать эти сведения рядом с реальными строками каталога. Начнём с одного доступного сервера, затем отделим подтверждённые факты этого стенда от правил для replica set.

Если MongoDB пока незнакома, сначала откройте документ, коллекцию и первый товар. Запись $object->method() означает вызов действия у объекта: класс, объект и метод. Manager хранит URI и настройки клиента и выполняет операции. Server представляет обнаруженный узел. Cursor позволяет прочитать ответ операции и узнать её Server. ServerDescription — отдельный неизменяемый снимок доступного описания узла.

Endpoint — адрес подключения: хост и порт. На учебном компьютере 127.0.0.1 означает этот же компьютер, а 27075 — выделенный порт MongoDB. Это не имя базы и не номер товара. Standalone — одиночный mongod. Replica set — несколько участников с общей репликацией и ролями; primary принимает обычную запись, secondary хранит реплицируемые данные. Подробнее: видимость, подтверждение и выбор реплики.

Когда $cursor уже получен запросом, первые два полезных действия укладываются в три строки. Переменная $server хранит объект узла; ->getHost() читает хост, ->getPort() — порт. Точка склеивает строки для вывода. Эти методы не перебирают товары и не печатают пароль из URI.

$server = $cursor->getServer();
echo $server->getHost(); // 127.0.0.1 на нашем стенде
echo ':'.$server->getPort(); // :27075

Этот фрагмент использует подготовленный Cursor. В самостоятельных программах ниже есть полное создание Manager, реальные запросы, видимые результаты и, где требуются товары, собственная коллекция с очисткой. URI и тип стенда выбраны явно, поэтому ожидаемые таблицы относятся к конкретному Standalone, а не ко всем возможным кластерам.

Manager, Server, Cursor и снимок: четыре разные задачи

Конфигурация, наблюдение и результат операции отвечают на разные вопросы. Если перепутать их, можно решить, что настройка secondary создала реплику, что read concern определяет адрес, а короткий RTT гарантирует быстрый каталог.

В этой главе URI использует directConnection=true, поэтому топология клиента — Single. Для доступного Standalone алгоритм выбора не отбирает узлы по read preference: выбирать между primary и secondary здесь не из кого. Поэтому secondary может успешно выбрать Standalone, у которого isSecondary=false. В replica set строгий secondary имеет другой смысл и может завершиться ошибкой, если подходящей реплики нет. Эти два случая нельзя смешивать.

Менять default объекта Manager ради одной операции не требуется. ReadPreference передаётся подходящему вызову, ReadConcern — Query или поддерживающей его команде, WriteConcern — записи. Собственные правила selectServer также важны: отсутствие аргумента означает primary, даже если в Manager задан secondaryPreferred.

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

Нужны PHP 8.4+ CLI, ext-mongodb 2.5+ и отдельный локальный MongoDB 8.0+. Composer для низкоуровневого Driver API не требуется. В README каждого ZIP приведены ссылки установки, проверка совпадения DLL со сборкой PHP, запуск mongod с bind_ip=127.0.0.1 и портом 27075. Standalone без аутентификации допустим здесь только как отдельный локальный учебный стенд.

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

Каждый ZIP распакуйте в свою папку вместе с ms122-helper.php и README. result.html показывает фактическую таблицу и раскрываемые диагностические данные; result.json содержит строки таблицы; metrics.json — версии, контрольные проверки и SHA256 файлов. Все восемь программ действительно обращаются к MongoDB. Пять читают диагностику без создания коллекций; три создают только собственную коллекцию со случайным именем и удаляют её в finally с проверкой отсутствия.

Увидеть сервер после настоящего обращения, а не по факту new Manager

При запуске приложения список известных серверов может быть пуст. Это ещё не означает, что сервер выключен: создание Manager и реальная команда — разные действия. Получим осмысленную проверку соединения и адрес сервера, который ответил.

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

Отдельный локальный mongod на 127.0.0.1:27075. Пока нет ни товаров, ни создаваемой коллекции: команда ping проверяет обмен с сервером. Manager создаётся с уникальным appname, чтобы пример не опирался на ранее использованное соединение.

Короткое действие

$before = $manager->getServers();
$manager->executeReadCommand('admin', new MongoDB\Driver\Command(['ping'=>1]));
$after = $manager->getServers();

Видимый результат

Разбор результата

getServers возвращает представление топологии, которое уже известно драйверу. Сам этот getter не принуждает его устанавливать соединение. В детали результата записано фактическое число описаний до команды; оно не подменяется предположением «всегда 0». После ping на нашем прямом одиночном подключении известен один узел. Host и port берутся из Server, а не из строки, заранее записанной в таблицу.

Ошибки и границы применения

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

<?php
declare(strict_types=1);
require __DIR__.'/ms122-helper.php';
$runtime=ms122Runtime();
[$manager,$database]=ms122Database([]);
$before=$manager->getServers();
$cursor=$manager->executeReadCommand('admin',new MongoDB\Driver\Command(['ping'=>1]));
$reply=$cursor->toArray()[0]; $used=$cursor->getServer();
$after=$manager->getServers(); $rows=[];
foreach ($after as $server) { $rows[]=[$server->getHost(),$server->getPort(),ms122Type($server),$reply->ok==1?'ping принят':'отказ']; }
$checks=['ping_acknowledged'=>$reply->ok==1,'one_known_server'=>count($after)===1,
    'observed_endpoint'=>ms122Endpoint($after[0])===ms122Endpoint($used),
    'standalone_after_contact'=>$used->getType()===MongoDB\Driver\Server::TYPE_STANDALONE,
    'before_is_observation'=>is_array($before)];
$details=['Сколько серверов было известно ДО ping'=>count($before),'Сколько известно ПОСЛЕ'=>count($after),
    'Почему первый размер не равен проверке связи'=>'getServers читает уже известное драйверу состояние; обязательного нуля до вызова не предполагаем'];
$checks['readonly_no_collection_created']=true;
$details['Область работы']='Только диагностика и чтение служебных ответов; коллекции не создавались';
$runtime['server']=ms122Command($manager,'admin',['buildInfo'=>1])[0]['version'];
ms122Report('mongodb122-server-lazy-discovery',['Хост', 'Порт', 'Фактический тип', 'Реальный ответ'],$rows,$checks,$runtime,$details);
echo 'mongodb122-server-lazy-discovery: saved result.html and result.json
';

mongodb122-server-lazy-discovery: saved result.html and result.json

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

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

Сравнить пять политик на одном standalone и не выдумать secondary

Разработчик записал secondary в настройках и решил, что чтение теперь обязательно идёт на вторую машину. Проверим это на нашем конкретном типе подключения: у standalone второй реплики вообще нет.

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

Один прямой Standalone. В Manager установлен secondaryPreferred и readConcern local. По очереди передаём selectServer пять разных ReadPreference; отдельно вызываем selectServer без аргумента. Никакие данные не меняются.

Короткое действие

$server = $manager->selectServer(new MongoDB\Driver\ReadPreference('secondary'));
echo $server->getType(); // TYPE_STANDALONE на этом direct-стенде, не RS_SECONDARY.

Видимый результат

Разбор результата

Для топологии Single спецификация выбора считает доступный единственный сервер подходящим и не применяет read preference как фильтр между репликами. Поэтому даже secondary здесь возвращает тот же Standalone с isSecondary=false. Это не модель поведения replica set. Вызов selectServer() без аргумента использует primary по своему контракту; он не подставляет автоматически secondaryPreferred из defaults Manager. Переданный объект выбирает режим данного вызова, но не перенастраивает Manager.

Ошибки и границы применения

Не переносите эту таблицу на replica set: там primary/secondary, теги и доступность узлов действительно участвуют в выборе, и строгий secondary может не найти сервер. Пять строк — проверка пяти вызовов в одном доступном standalone, а не испытание распределения нагрузки или отказоустойчивости. Пустые getTags здесь означают отсутствие тегов, а не список всех возможных тегов кластера.

<?php
declare(strict_types=1);
require __DIR__.'/ms122-helper.php';
$runtime=ms122Runtime();
[$manager,$database]=ms122Database(['readPreference'=>'secondaryPreferred','readConcernLevel'=>'local']);
$before=ms122Policies($manager); $rows=[]; $endpoints=[]; $tags=[];
foreach (['primary','primaryPreferred','secondary','secondaryPreferred','nearest'] as $mode) {
    $preference=new MongoDB\Driver\ReadPreference($mode);
    $server=$manager->selectServer($preference);
    $rows[]=[$preference->getModeString(),ms122Endpoint($server),ms122Type($server),$server->isSecondary()?'true':'false'];
    $endpoints[]=ms122Endpoint($server); $tags[]=$server->getTags();
}
$implicit=$manager->selectServer();
$ping=ms122Command($manager,'admin',['ping'=>1])[0];
$after=ms122Policies($manager);
$checks=['all_same_endpoint'=>count(array_unique($endpoints))===1,
    'standalone_selected'=>$implicit->getType()===MongoDB\Driver\Server::TYPE_STANDALONE,
    'manager_policy_not_mutated'=>$before===$after && $after['readPreference']==='secondaryPreferred' && $after['readConcern']==='local' && $after['w']===1,
    'tags_really_empty'=>$tags===[[],[],[],[],[]],'server_answers'=>$ping['ok']==1];
$details=['Настройки Manager до'=>$before,'Настройки Manager после'=>$after,'Реальные теги каждого выбранного сервера'=>$tags,
    'Вызов selectServer без параметра'=>ms122Endpoint($implicit),'Объяснение'=>'directConnection=true задаёт топологию Single; она игнорирует ReadPreference при выборе доступного единственного узла'];
$checks['readonly_no_collection_created']=true;
$details['Область работы']='Только диагностика и чтение служебных ответов; коллекции не создавались';
$runtime['server']=ms122Command($manager,'admin',['buildInfo'=>1])[0]['version'];
ms122Report('mongodb122-server-selection-modes',['Переданный режим', 'Endpoint', 'Тип', 'Это RS secondary?'],$rows,$checks,$runtime,$details);
echo 'mongodb122-server-selection-modes: saved result.html and result.json
';

mongodb122-server-selection-modes: saved result.html and result.json

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

Упражнение и направление решения. В таблице найдите secondary и сравните его с isSecondary. Почему false не является ошибкой? Ответ: политика выбора применяется в контексте топологии; данное прямое подключение Single не создаёт вторичный узел. Для опытов с replica set используйте отдельную главу о согласованности.

Практический вопрос: Set mongodb read preference at mongo server level. Автор ищет серверную глобальную настройку маршрутизации чтения. Наше объяснение показывает клиентский ReadPreference, сохранность defaults и зависимость выбора от Single/replica-set топологии. Обсуждение определяет задачу; текущие контракты драйвера и правила выбора сверены с первичной документацией.

Прочитать карточку с параметрами вызова и установить её настоящий сервер

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

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

В собственной коллекции два товара: CUP за 500 и LAMP за 1200. Defaults Manager: secondaryPreferred, read concern явно не задан. У Query фильтр sku=CUP, проекция sku/price без _id, limit=1 и явный readConcern local. Только executeQuery получает ReadPreference primary.

Короткое действие

$cursor = $manager->executeQuery($namespace, $query,
    ['readPreference'=>new MongoDB\Driver\ReadPreference('primary')]);
$server = $cursor->getServer();
echo $server->getHost(), ':', $server->getPort();

Видимый результат

Разбор результата

readConcern описывает требуемый уровень видимости данных, readPreference — правило выбора сервера; это разные настройки. Query получает первый объект, опции executeQuery — второй. Возвращённый Cursor знает фактический Server. После чтения getReadPreference и getReadConcern у Manager показывают прежние значения. NULL уровня означает «не задан явно», а не отсутствие данных и не доказательство конкретного серверного default.

Ошибки и границы применения

На единственном Standalone нельзя доказать переход с secondary на primary: ни одной такой пары здесь нет. Этот пример реально проверяет данные, объекты настроек, сохранность defaults и endpoint. Смысл этих политик при репликации разбирается на отдельном replica set. Не составляйте фильтр MongoDB напрямую из произвольного пользовательского массива; приложение само задаёт допустимые поля и операторы.

<?php
declare(strict_types=1);
require __DIR__.'/ms122-helper.php';
$runtime=ms122Runtime();
[$manager,$database]=ms122Database(['readPreference'=>'secondaryPreferred']);
$collection='mongodb122_server_'.bin2hex(random_bytes(8)); $namespace=$database.'.'.$collection; $owned=false;
if (ms122Exists($manager,$database,$collection)) { throw new RuntimeException('Unexpected collection collision'); }
try {
    ms122Command($manager,$database,['create'=>$collection],true); $owned=true;
ms122Seed($manager,$namespace,[['_id'=>1,'sku'=>'CUP','price'=>500],['_id'=>2,'sku'=>'LAMP','price'=>1200]]);
$before=ms122Policies($manager);
$readConcern=new MongoDB\Driver\ReadConcern('local'); $readPreference=new MongoDB\Driver\ReadPreference('primary');
$query=new MongoDB\Driver\Query(['sku'=>'CUP'],['projection'=>['_id'=>0,'sku'=>1,'price'=>1],'limit'=>1,'readConcern'=>$readConcern,'maxTimeMS'=>1000]);
$cursor=$manager->executeQuery($namespace,$query,['readPreference'=>$readPreference]);
$cursor->setTypeMap(['root'=>'array','document'=>'array','array'=>'array']); $documents=$cursor->toArray();
$server=$cursor->getServer(); $after=ms122Policies($manager);
$rows=[[$documents[0]['sku'],$documents[0]['price'],ms122Endpoint($server),$readPreference->getModeString(),$after['readPreference']]];
$checks=['exact_screen_data'=>$documents===[['sku'=>'CUP','price'=>500]],
    'manager_defaults_unchanged'=>$before===$after && $after['readPreference']==='secondaryPreferred' && $after['readConcern']===null,
    'explicit_query_policy'=>$readConcern->getLevel()==='local' && $readPreference->getModeString()==='primary',
    'actual_cursor_server'=>$server->getHost()==='127.0.0.1' && $server->getType()===MongoDB\Driver\Server::TYPE_STANDALONE];
$details=['Manager до'=>$before,'Параметры этого вызова'=>['readConcern'=>$readConcern->getLevel(),'readPreference'=>$readPreference->getModeString()],
    'Manager после'=>$after,'Вывод'=>'Настройки вызова не изменяют настройки Manager. Единственный узел не доказывает маршрутизацию между репликами.'];
} finally {
    if ($owned) { ms122Command($manager,$database,['drop'=>$collection],true); }
}
$checks['owned_collection_removed']=!ms122Exists($manager,$database,$collection);
$details['Собственная удалённая коллекция']=$collection;
$runtime['server']=ms122Command($manager,'admin',['buildInfo'=>1])[0]['version'];
ms122Report('mongodb122-server-query-origin',['Артикул', 'Цена', 'Сервер результата', 'Режим вызова', 'Режим Manager после'],$rows,$checks,$runtime,$details);
echo 'mongodb122-server-query-origin: saved result.html and result.json
';

mongodb122-server-query-origin: saved result.html and result.json

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

Упражнение и направление решения. Замените только sku=CUP на sku=LAMP. В проекции останутся те же два поля, limit ограничит ответ одной карточкой, ожидаемая цена станет 1200. Переделывать Manager ради одного такого фильтра не требуется.

Практический вопрос: Global read preference vs query-level read preference. У клиента общий secondaryPreferred, а отдельное чтение должно иметь собственную политику. Пример разделяет default Manager, явные опции операции и фактический Server ответа; чужой API из обсуждения не переносится на PHP. Обсуждение определяет задачу; текущие контракты драйвера и правила выбора сверены с первичной документацией.

Изменить требование подтверждения одного вызова, сохранив настройки Manager

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

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

Manager с w=1 и journal=false. Для одной вставки PAID-CUP за 750 создаётся WriteConcern(1, 1500, true): подтверждение от узла, срок ожидания write concern 1500 мс и запрос journal. В собственной коллекции после записи читаются sku и price.

Короткое действие

$callConcern = new MongoDB\Driver\WriteConcern(1, 1500, true);
$result = $manager->executeBulkWrite($namespace, $bulk, ['writeConcern'=>$callConcern]);
$stillDefault = $manager->getWriteConcern(); // прежняя настройка Manager

Видимый результат

Разбор результата

Возвращённый getWriteConcern объект описывает defaults Manager. Чтобы изменить условия конкретной записи, новый объект передаётся этой операции. В таблице сравниваются три реальные пары w/journal; в деталях — прочитанный товар и факт подтверждения. getJournal возвращает bool или NULL: false — явно выбранное значение, NULL — значение явно не задано. Этот пример специально задаёт false, чтобы различие было видно.

Ошибки и границы применения

journal=true не делает программу тестом переживания аварии: здесь не отключается питание, не проверяется восстановление и нет нескольких реплик. w=1 не обеспечивает majority на настоящем наборе реплик. wtimeout — срок ожидания нужного подтверждения, а не универсальный таймер всех сетевых действий и не автоматический откат записи. Имя PAID-CUP обозначает учебный товар, а не готовую платёжную систему.

<?php
declare(strict_types=1);
require __DIR__.'/ms122-helper.php';
$runtime=ms122Runtime();
[$manager,$database]=ms122Database(['journal'=>false]);
$collection='mongodb122_server_'.bin2hex(random_bytes(8)); $namespace=$database.'.'.$collection; $owned=false;
if (ms122Exists($manager,$database,$collection)) { throw new RuntimeException('Unexpected collection collision'); }
try {
    ms122Command($manager,$database,['create'=>$collection],true); $owned=true;
$before=$manager->getWriteConcern();
$callConcern=new MongoDB\Driver\WriteConcern(1,1500,true);
$bulk=new MongoDB\Driver\BulkWrite; $bulk->insert(['_id'=>3,'sku'=>'PAID-CUP','price'=>750]);
$result=$manager->executeBulkWrite($namespace,$bulk,['writeConcern'=>$callConcern]);
$after=$manager->getWriteConcern();
$cursor=$manager->executeQuery($namespace,new MongoDB\Driver\Query(['_id'=>3],['projection'=>['_id'=>0,'sku'=>1,'price'=>1],'limit'=>1,'maxTimeMS'=>1000]));
$cursor->setTypeMap(['root'=>'array']); $documents=$cursor->toArray();
$rows=[['Manager до',$before->getW(),$before->getJournal()?'true':'false'],
    ['Только этот вызов',$callConcern->getW(),$callConcern->getJournal()?'true':'false'],
    ['Manager после',$after->getW(),$after->getJournal()?'true':'false']];
$checks=['manager_unchanged'=>$before->getW()===1 && $after->getW()===1 && $before->getJournal()===false && $after->getJournal()===false,
    'call_requests_journal'=>$callConcern->getJournal()===true && $callConcern->getWtimeout()===1500,
    'acknowledged_insert'=>$result->isAcknowledged() && $result->getInsertedCount()===1,
    'actual_saved_product'=>$documents===[['sku'=>'PAID-CUP','price'=>750]]];
$details=['Фактически прочитанный товар'=>$documents,'Подтверждение'=>$result->isAcknowledged(),
    'Граница'=>'Один успешный journaled-вызов не является испытанием восстановления после аварии. w=1 не означает несколько реплик.'];
} finally {
    if ($owned) { ms122Command($manager,$database,['drop'=>$collection],true); }
}
$checks['owned_collection_removed']=!ms122Exists($manager,$database,$collection);
$details['Собственная удалённая коллекция']=$collection;
$runtime['server']=ms122Command($manager,'admin',['buildInfo'=>1])[0]['version'];
ms122Report('mongodb122-server-write-defaults',['Источник настройки', 'w', 'journal'],$rows,$checks,$runtime,$details);
echo 'mongodb122-server-write-defaults: saved result.html and result.json
';

mongodb122-server-write-defaults: saved result.html and result.json

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

Упражнение и направление решения. Найдите, какой объект передан executeBulkWrite, и какой читает последующий getWriteConcern. Это разные настройки: per-call concern передан операции, а getter возвращает default Manager. Поэтому последняя строка таблицы остаётся false.

Не считать исправный standalone сломанным из-за isPrimary=false

Диагностическая страница показывает isPrimary=false, хотя обычные операции с базой работают. Вместо ошибочного сообщения «нет главного сервера» различим тип узла, способность принять запись и роль в replica set.

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

Фактически выбранный Standalone. getInfo даёт доступное описание hello; поле isWritablePrimary, либо историческое имя ismaster, сообщает writable. Методы isPrimary/isSecondary/isArbiter/isHidden/isPassive относятся к ролям или свойствам replica set.

Короткое действие

echo $server->getType();   // TYPE_STANDALONE
var_export($server->isPrimary()); // false: это НЕ primary-член replica set
$hello = $server->getInfo(); // описание последнего наблюдения

Видимый результат

Разбор результата

Одиночный mongod может принимать запись, оставаясь не RSPrimary. Поэтому writable=true и isPrimary=false здесь не противоречат друг другу. isHidden означает скрытого члена replica set, isPassive — участника с приоритетом 0, isArbiter — арбитра, не хранящего пользовательские данные. Эти понятия не следует сводить к одной общей проверке «сервер хороший/плохой».

Ошибки и границы применения

getInfo — мониторинговое описание, а не транзакционная гарантия следующей операции. Не маршрутизируйте прикладную запись вручную по однажды прочитанному isPrimary: драйвер выбирает подходящий сервер для операции. На standalone мы честно проверяем отрицательные RS-признаки; положительные состояния hidden/arbiter/secondary и смена лидера в этом примере не воспроизводятся.

<?php
declare(strict_types=1);
require __DIR__.'/ms122-helper.php';
$runtime=ms122Runtime();
[$manager,$database]=ms122Database([]);
$server=$manager->selectServer(); $info=$server->getInfo(); $roles=ms122Roles($server);
$writable=(bool)($info['isWritablePrimary']??$info['ismaster']??false);
$rows=[['Тип сервера',ms122Type($server)],['hello: writable',$writable?'true':'false']];
foreach ($roles as $name=>$value) { $rows[]=[$name,$value?'true':'false']; }
$rows[]=['RS tags',$server->getTags()===[]?'пусто':'заданы'];
$description=$server->getServerDescription();
$checks=['standalone_type'=>$server->getType()===MongoDB\Driver\Server::TYPE_STANDALONE,
    'writable_hello'=>$writable,'all_rs_flags_false'=>$roles===['isPrimary'=>false,'isSecondary'=>false,'isArbiter'=>false,'isHidden'=>false,'isPassive'=>false],
    'no_replica_set_tags'=>$server->getTags()===[],'description_agrees'=>$description->getType()==='Standalone'];
$details=['Endpoint'=>ms122Endpoint($server),'Последний hello'=>$info,
    'Значение признаков'=>'isPrimary означает primary-члена replica set, а не произвольный сервер, который принимает обычную запись'];
$checks['readonly_no_collection_created']=true;
$details['Область работы']='Только диагностика и чтение служебных ответов; коллекции не создавались';
$runtime['server']=ms122Command($manager,'admin',['buildInfo'=>1])[0]['version'];
ms122Report('mongodb122-server-role-vs-writable',['Признак', 'Наблюдаемое значение'],$rows,$checks,$runtime,$details);
echo 'mongodb122-server-role-vs-writable: saved result.html and result.json
';

mongodb122-server-role-vs-writable: saved result.html and result.json

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

Упражнение и направление решения. Исправьте диагностическое правило «если !isPrimary, сервер недоступен». Направление решения: сначала покажите getType; для проверки доступности используйте реальную команду, а RS-роль выводите отдельным полем без подмены способности принять запрос.

Практический вопрос: Will an application written for standalone MongoDB work for replica-set or sharded cluster?. Переезд с одиночного mongod вызывает путаницу в ролях, URI и возможностях. Пример отделяет Standalone от RSPrimary и writable от RS-роли, не изображая тест репликации на одном standalone. Обсуждение определяет задачу; текущие контракты драйвера и правила выбора сверены с первичной документацией.

Сохранить снимок описания сервера для диагностического отчёта

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

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

Первый ServerDescription получается из выбранного Server. Сохраняются host, port, type и каноническое представление его hello. Затем реально выполняется ping и запрашивается новый ServerDescription.

Короткое действие

$snapshot = $server->getServerDescription();
$typeAtCapture = $snapshot->getType(); // строка "Standalone"
// Это сохранённое значение, не живое обещание будущей роли сервера.

Видимый результат

Разбор результата

ServerDescription неизменяем: старое описание сохраняет полученные значения. Новое надо запрашивать отдельно. В нашем спокойном одиночном стенде A и B показывают один Standalone; программа не придумывает смену роли. Канонический JSON hello сравнивается для сохранённого A, чтобы не спутать смысл BSON-значений с идентичностью PHP-объектов. Server::getType возвращает int-константу, а ServerDescription::getType — строковое имя типа.

Ошибки и границы применения

Одинаковые снимки до и после ping не доказывают отсутствие промежуточных событий в реальном кластере. getLatency относится к измерению hello, а не времени между двумя снимками или длительности ping в нашем PHP-коде. На некоторых топологиях задержка может быть NULL; это следует показывать как неизвестное значение, а не ноль.

<?php
declare(strict_types=1);
require __DIR__.'/ms122-helper.php';
$runtime=ms122Runtime();
[$manager,$database]=ms122Database([]);
$server=$manager->selectServer(); $snapshot=$server->getServerDescription();
$originalHello=MongoDB\BSON\Document::fromPHP($snapshot->getHelloResponse())->toCanonicalExtendedJSON();
$originalType=$snapshot->getType(); $originalHost=$snapshot->getHost(); $originalPort=$snapshot->getPort();
$rows=[['Снимок до ping',$originalHost,$originalPort,$originalType]];
ms122Command($manager,'admin',['ping'=>1]);
$fresh=$server->getServerDescription();
$rows[]=['Тот же сохранённый снимок',$snapshot->getHost(),$snapshot->getPort(),$snapshot->getType()];
$rows[]=['Новый снимок после ping',$fresh->getHost(),$fresh->getPort(),$fresh->getType()];
$latency=$server->getLatency();
$checks=['snapshot_value_unchanged'=>$originalHello===MongoDB\BSON\Document::fromPHP($snapshot->getHelloResponse())->toCanonicalExtendedJSON(),
    'same_observed_endpoint'=>$originalHost===$fresh->getHost() && $originalPort===$fresh->getPort(),
    'standalone_descriptions'=>$originalType==='Standalone' && $fresh->getType()==='Standalone',
    'latency_contract'=>$latency===null || (is_int($latency) && $latency>=0)];
$details=['Сохранённый hello'=>json_decode($originalHello,true,512,JSON_THROW_ON_ERROR),
    'Новый hello'=>$fresh->getHelloResponse(),'getLatency_ms'=>$latency,
    'Граница'=>'В этом запуске роль не менялась. Отсутствие изменений не является тестом failover; неизменяемость объекта следует контракту ServerDescription.'];
$checks['readonly_no_collection_created']=true;
$details['Область работы']='Только диагностика и чтение служебных ответов; коллекции не создавались';
$runtime['server']=ms122Command($manager,'admin',['buildInfo'=>1])[0]['version'];
ms122Report('mongodb122-server-description-snapshot',['Состояние отчёта', 'Хост', 'Порт', 'Тип снимка'],$rows,$checks,$runtime,$details);
echo 'mongodb122-server-description-snapshot: saved result.html and result.json
';

mongodb122-server-description-snapshot: saved result.html and result.json

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

Упражнение и направление решения. Для отчёта «до/после» сохраните два отдельных результата getServerDescription. Не заменяйте сохранённый A новым B. Если оба показывают Standalone, так и запишите; успешный пример не требует искусственно рисовать изменение топологии.

Проверить небольшую порцию по объявленным возможностям сервера

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

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

Учебный товар содержит sku=CUP и price=500; его реальный BSON-размер получаем через Document::fromPHP и strlen сырых BSON-байтов. План порции — три документа. getInfo поставляет наблюдаемые maxBsonObjectSize, maxWriteBatchSize и maxMessageSizeBytes.

Короткое действие

$info = $server->getInfo();
$maxBytes = $info['maxBsonObjectSize'];
$latencyMs = $server->getLatency(); // hello RTT; это не время выполнения вашего find

Видимый результат

Разбор результата

Первое сравнение относится к одному BSON-документу, второе — к числу write-операций в серверной порции. Это разные размеры. В result.html раскрываются реальные числовые лимиты и число байтов товара; таблица показывает смысл результата. getLatency выводится отдельно: сетевой hello RTT не превращается в оценку скорости обработки прайса.

Ошибки и границы применения

Эта программа не вставляет три товара, не испытывает максимальный размер сообщения и не подменяет упаковку/разбиение команд самим драйвером. Накладные расходы wire protocol не равны сумме strlen товаров. Предварительная оценка не отменяет обработку серверной ошибки. В load-balanced режиме getInfo и getType могут описывать разные уровни подключения; специальный случай подробно указан в карточке getInfo.

<?php
declare(strict_types=1);
require __DIR__.'/ms122-helper.php';
$runtime=ms122Runtime();
[$manager,$database]=ms122Database([]);
$server=$manager->selectServer(); $info=$server->getInfo();
$product=['sku'=>'CUP','price'=>500]; $bsonBytes=strlen((string)MongoDB\BSON\Document::fromPHP($product));
$plannedDocuments=3;
$maxBson=$info['maxBsonObjectSize']??null; $maxBatch=$info['maxWriteBatchSize']??null;
if (!is_int($maxBson) || !is_int($maxBatch) || $maxBson<=0 || $maxBatch<=0) { throw new RuntimeException('Expected positive hello capabilities'); }
$fitsDocument=$bsonBytes<=$maxBson; $fitsCount=$plannedDocuments<=$maxBatch;
$latency=$server->getLatency();
$rows=[['Товар CUP','sku=CUP; price=500',$fitsDocument?'помещается в BSON-лимит':'слишком велик'],
    ['План порции','3 документа',$fitsCount?'не превышает лимит числа операций':'нужно разбить'],
    ['Тип подключения',ms122Type($server),'проверены наблюдаемые ограничения']];
$checks=['document_fits'=>$fitsDocument,'planned_count_fits'=>$fitsCount,
    'latency_contract'=>$latency===null || (is_int($latency) && $latency>=0),
    'actual_hello'=>array_key_exists('maxMessageSizeBytes',$info) && $server->getType()===MongoDB\Driver\Server::TYPE_STANDALONE];
$details=['Байты BSON товара'=>$bsonBytes,'maxBsonObjectSize'=>$maxBson,'maxWriteBatchSize'=>$maxBatch,
    'maxMessageSizeBytes'=>$info['maxMessageSizeBytes'],'getLatency_ms'=>$latency,
    'Не проверено'=>'Вставка этой порции, расходы полного wire message и максимальная производительность. Это предварительная диагностика, не ручной заменитель упаковки драйвера.'];
$checks['readonly_no_collection_created']=true;
$details['Область работы']='Только диагностика и чтение служебных ответов; коллекции не создавались';
$runtime['server']=ms122Command($manager,'admin',['buildInfo'=>1])[0]['version'];
ms122Report('mongodb122-server-server-capabilities',['Что проверяем', 'Данные', 'Вывод по реальному hello'],$rows,$checks,$runtime,$details);
echo 'mongodb122-server-server-capabilities: saved result.html and result.json
';

mongodb122-server-server-capabilities: saved result.html and result.json

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

Упражнение и направление решения. Добавьте к учебному товару описание и снова сравните фактическое число BSON-байтов. Сохраняйте ключи и типы документа, не считайте размер по количеству PHP-элементов. Для следующего шага используйте главу о пакетной записи и её реальных результатах.

Приложить к экрану товаров фактический endpoint и честную диагностику

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

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

CUP за 500, LAMP за 1200 и MAT за 300. Для экрана нужны товары от 500: только sku и price, сортировка по price/sku, limit=2. Manager явно задаёт readConcern local, остальные нужные defaults читаются из его объектов.

Короткое действие

$server = $cursor->getServer();
$diagnostics = ['host'=>$server->getHost(), 'port'=>$server->getPort(),
    'type'=>$server->getType(), 'helloLatencyMs'=>$server->getLatency()];
// Поля данных выбираются в запросе; диагностика относится к серверу этого Cursor.

Видимый результат

Разбор результата

Две строки строятся из реального ответа базы. Host/port/type берутся у Server этого Cursor; getServers служит дополнительным описанием известной топологии. Таблица не сортируется после загрузки всех товаров в PHP. В раскрывающемся блоке отдельно показаны запрос, defaults Manager, отрицательные RS-признаки и фактический snapshot. Это данные для диагностики, а не публичный отчёт для всех посетителей сайта.

Ошибки и границы применения

Данные hello могут раскрывать внутренние адреса и параметры инфраструктуры: в рабочем приложении доступ к такой диагностике ограничивают. URI с паролем вообще не следует печатать. Один короткий запрос не измеряет нагрузку; latency не доказывает его медленную или быструю обработку. Список getServers и снимок актуальны на момент наблюдения, последующие запросы в replica set могут обслуживаться иначе.

<?php
declare(strict_types=1);
require __DIR__.'/ms122-helper.php';
$runtime=ms122Runtime();
[$manager,$database]=ms122Database(['readConcernLevel'=>'local']);
$collection='mongodb122_server_'.bin2hex(random_bytes(8)); $namespace=$database.'.'.$collection; $owned=false;
if (ms122Exists($manager,$database,$collection)) { throw new RuntimeException('Unexpected collection collision'); }
try {
    ms122Command($manager,$database,['create'=>$collection],true); $owned=true;
ms122Seed($manager,$namespace,[['_id'=>1,'sku'=>'CUP','price'=>500],['_id'=>2,'sku'=>'LAMP','price'=>1200],['_id'=>3,'sku'=>'MAT','price'=>300]]);
$cursor=$manager->executeQuery($namespace,new MongoDB\Driver\Query(['price'=>['$gte'=>500]],
    ['projection'=>['_id'=>0,'sku'=>1,'price'=>1],'sort'=>['price'=>1,'sku'=>1],'limit'=>2,'maxTimeMS'=>1000]));
$cursor->setTypeMap(['root'=>'array']); $documents=$cursor->toArray(); $server=$cursor->getServer();
$rows=[]; foreach ($documents as $document) { $rows[]=[$document['sku'],$document['price'],$server->getHost(),$server->getPort(),ms122Type($server)]; }
$roles=ms122Roles($server); $latency=$server->getLatency(); $snapshot=$server->getServerDescription();
$known=$manager->getServers(); $tags=$server->getTags(); $policies=ms122Policies($manager);
$checks=['bounded_screen'=>$documents===[['sku'=>'CUP','price'=>500],['sku'=>'LAMP','price'=>1200]],
    'one_known_endpoint'=>count($known)===1 && ms122Endpoint($known[0])===ms122Endpoint($server),
    'standalone_not_rs'=>$roles===['isPrimary'=>false,'isSecondary'=>false,'isArbiter'=>false,'isHidden'=>false,'isPassive'=>false],
    'empty_actual_tags'=>$tags===[],'snapshot_matches'=>$snapshot->getType()==='Standalone',
    'latency_contract'=>$latency===null || (is_int($latency) && $latency>=0),
    'configured_policy'=>$policies['readPreference']==='primary' && $policies['readConcern']==='local' && $policies['w']===1];
$details=['Фильтр'=>['price'=>['$gte'=>500]],'Проекция/сортировка/лимит'=>['fields'=>['sku','price'],'sort'=>['price'=>1,'sku'=>1],'limit'=>2],
    'RS-признаки фактического сервера'=>$roles,'Теги'=>$tags,'Настройки Manager'=>$policies,
    'getLatency_ms'=>$latency,'Снимок hello'=>$snapshot->getHelloResponse(),
    'Не делаем вывод'=>'Две строки не являются измерением нагрузки, latency не является длительностью их получения, вторичная реплика не испытывалась'];
} finally {
    if ($owned) { ms122Command($manager,$database,['drop'=>$collection],true); }
}
$checks['owned_collection_removed']=!ms122Exists($manager,$database,$collection);
$details['Собственная удалённая коллекция']=$collection;
$runtime['server']=ms122Command($manager,'admin',['buildInfo'=>1])[0]['version'];
ms122Report('mongodb122-server-diagnostic-report',['Артикул', 'Цена', 'Фактический хост', 'Порт', 'Тип'],$rows,$checks,$runtime,$details);
echo 'mongodb122-server-diagnostic-report: saved result.html and result.json
';

mongodb122-server-diagnostic-report: saved result.html and result.json

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

Упражнение и направление решения. Добавьте товар BOOK за 800. При том же фильтре и сортировке первые две строки должны стать CUP и BOOK, а LAMP уйдёт за limit. Endpoint останется фактическим свойством Cursor, а не ручной характеристикой товара.

Пять методов Manager и двенадцать методов Server

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

Сохранить полезный отчёт и перейти к работе с ответом

Для диагностического отчёта сначала сохраните нужные данные запроса и фактический Server его Cursor. Defaults Manager записывайте отдельно от per-call опций. Тип, RS-роли, теги и снимок помогают объяснить окружение, но не заменяют обработку ошибок реальной операции. Не переносите поведение Single на replica set без учёта правил выбора.

Следующие связанные шаги: читать Cursor порциями и сохранять место обхода, проверять read/write concern на replica set, согласовывать многодокументные действия транзакцией, получать понятную квитанцию записи. Если запрос медленный, исследуйте его фильтр, индекс, объём результата и план; одна величина hello RTT не отвечает на эти вопросы.