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

Получить понятную историю подключения

В сервисе нужна понятная история подключения: клиент создан, узел ещё неизвестен, проверка прошла или отказала, клиент освобождён. Без такой истории легко принять Single за успешное соединение, старый снимок — за текущее состояние, а закрытие клиента — за остановку MongoDB. Здесь построим небольшой журнал настоящих событий и свяжем его с полезным чтением каталога.

Предварительные понятия: документ, коллекция и первый товар, Manager, Server и реальный источник ответа, объект и метод. Топология — известная клиенту картина подключения: какие узлы обнаружены и как организован доступ к ним. Снимок сохраняет эту картину на один момент. Событие сообщает о произошедшем изменении. Подписчик — наш объект, которому драйвер передаёт события вызовом его методов.

SDAM означает Server Discovery and Monitoring: обнаружение и мониторинг серверов. Это служебная работа драйвера, а не перебор товаров. Heartbeat — проверка серверного hello; её начало, успех и отказ отличаются от результата пользовательского find/insert. У Single есть один прямой endpoint; Standalone — тип обнаруженного mongod. Эти имена относятся к разным уровням.

Самое короткое полезное чтение, когда снимок уже пришёл из события: первая строка сохраняет логический ответ в переменную, echo показывает понятный текст. Знак -> вызывает метод объекта; ?: выбирает один из двух текстов. Этот getter не соединяется с сервером заново.

$readable = $snapshot->hasReadableServer();
echo $readable ? 'В снимке есть читаемый узел' : 'Подходящий узел пока не известен';

Чтобы получить $snapshot, реализуем метод интерфейса SDAMSubscriber. Интерфейс — договор о названиях, входных параметрах и результате методов; драйвер умеет обращаться к любому объекту с таким договором. $event является параметром метода, который заполняет сам драйвер. : void означает, что обработчик сохраняет наблюдение и не возвращает значение.

public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent $event): void {
    $this->snapshot = $event->getNewDescription();
}

Это короткая часть класса, а не самостоятельный файл. Полная реализация всех девяти методов есть в helper каждого ZIP. Никто не вызывает их вручную для получения красивой таблицы: сначала регистрируется объект, затем выполняется настоящая команда. Регистрация, обработчик события и операция базы — три отдельных действия.

Событие, подписчик и неизменяемый снимок

Для отчёта полезно сохранять и смысл действия, и границу его доказательства. Снимок — фотография известного клиенту состояния: он не обновляется сам и не является сетевой проверкой в момент чтения getter.

Global-подписчик регистрируется функцией Monitoring\addSubscriber и видит события любых Manager. Manager::addSubscriber ограничивает область одним Manager. Один и тот же объект не получает одно событие дважды из-за повторной регистрации или сочетания global+Manager. Для снятия используются соответствующие removeSubscriber: удаление одной регистрации не удаляет другую. Наблюдать открытие удобнее глобально до создания Manager, а закрытие — глобально после освобождения всех ссылок на непостоянный клиент.

getNewDescription и getPreviousDescription возвращают TopologyDescription. Его getServers возвращает ServerDescription, а не подключаемые объекты Server из Manager::getServers. topologyId — ObjectId для клиентской топологии; это не _id документа и не обязательный идентификатор физического кластера. Когда два клиента используют один адрес, такой ключ позволяет разделить их истории.

Callbacks должны быть короткими. В этой главе они только добавляют ограниченную запись и обновляют счётчик в памяти. Журнал хранит до четырёх идентичностей и 16 переходов; обычный список событий ограничен 64 записями, в последнем задании — шестью. Политика переполнения видна через discarded. Медленный HTTP-запрос или новый MongoDB-запрос внутри callback менял бы работу наблюдаемой программы.

Запустить стенд и самостоятельные программы

Нужны PHP 8.4+ CLI, ext-mongodb 2.5+ и отдельный локальный MongoDB Community 8.0+. Composer не нужен. README каждого ZIP объясняет установку DLL под версию PHP/TS/NTS/x64, проверку php.ini и запуск mongod с отдельным dbpath, 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

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

Для настоящих lifecycle-событий helper создаёт Manager с disableClientPersistence=true и освобождает его до завершения request. Для контролируемого отказа программа резервирует собственный loopback-порт без LISTEN и ограничивает connect/selection timeout; существующий MongoDB продолжает работать. Не копируйте случайный номер из результата: порт каждый раз выдаёт ОС, и он удерживается нашим сокетом до очистки.

Получить статус подключения из настоящего события, а не из new Manager

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

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

Один локальный mongod на 127.0.0.1:27075. До создания Manager регистрируется объект Mt123Journal. Его метод topologyChanged вызывается драйвером; он сохраняет старое и новое описание. Сам конструктор не обязан доставить события: сначала выполняется ping, затем из настоящего события обнаружения берётся пара прежнего и нового описаний.

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

public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent $event): void {
    $snapshot = $event->getNewDescription();
    $this->readable = $snapshot->hasReadableServer();
} // Метод вызывает драйвер после регистрации объекта-подписчика.

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

Почему получился такой результат

В обеих строках тип Single: это топология прямого подключения, а не синоним «соединение проверено». В previousDescription события hasReadableServer и hasWritableServer возвращают false. В newDescription после обнаружения есть один Standalone. Оба описания программа получает из настоящего события во время первого ping, а не читает пустой журнал до обращения. В раскрываемом журнале видны topologyOpening, serverOpening, heartbeat и изменения описания; события вручную не создаются.

Ошибки и ограничения

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

<?php
declare(strict_types=1);
require __DIR__.'/mt123-helper.php';
$runtime=mt123Runtime();
[$uri,$database]=mt123Config();
$journal=new Mt123Journal; $manager=null;
MongoDB\Driver\Monitoring\addSubscriber($journal);
try {
    $manager=mt123Manager($uri); $ping=mt123Ping($manager,$database);
    $transition=null;
    foreach ($journal->changes as $change) {
        if ($change['old']->getType()==='Single' && !$change['old']->hasReadableServer()
            && $change['new']->hasReadableServer()) { $transition=$change; break; }
    }
    if ($transition===null) { throw new RuntimeException('Expected actual discovery transition'); }
    $before=$transition['old']; $after=$transition['new'];
    $servers=$after->getServers();
    $rows=[['Прежнее описание из события',$before->getType(),$before->hasReadableServer(),$before->hasWritableServer(),count($before->getServers())],
        ['Новое описание после ping',$after->getType(),$after->hasReadableServer(),$after->hasWritableServer(),count($servers)]];
    $checks=['real_ping'=>$ping,'actual_standalone'=>count($servers)===1 && $servers[0]->getType()==='Standalone',
        'real_notifications'=>$journal->count('topologyOpening')===1 && $journal->count('serverOpening')===1
            && $journal->count('serverHeartbeatStarted')>=1 && $journal->count('serverHeartbeatSucceeded')>=1
            && $journal->count('serverChanged')>=1 && $journal->count('topologyChanged')>=2];
} finally {
    unset($manager); MongoDB\Driver\Monitoring\removeSubscriber($journal);
}
$checks['actual_close']=$journal->count('topologyClosed')===1 && $journal->count('serverClosed')===1;
$details=['Настоящий журнал'=>$journal->events,'Счётчики'=>$journal->counts,'Снимок после ping'=>mt123Snapshot($after),
    'Граница'=>'Снимок пригодности не заменяет try/catch у следующего запроса; topologyOpening не подтверждает подключение'];
$runtime['server']=mt123BuildVersion($uri,$database);
$expected=[['Прежнее описание из события', 'Single', false, false, 0], ['Новое описание после ping', 'Single', true, true, 1]];
$checks['expected_rows']=$rows===$expected;
mt123Report('mongodb123-topology-connect-status',['Момент', 'Топология', 'Есть читаемый узел', 'Есть writable узел', 'Известных описаний'],$rows,$checks,$runtime,$details);
echo 'mongodb123-topology-connect-status: OK',"\n";

mongodb123-topology-connect-status: OK

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

Упражнение и направление решения. Если интерфейс показывает только «Single», можно ли считать базу доступной? Нет: посмотрите прежнее описание из события. Для статуса различайте тип топологии, известную пригодность узла и результат реальной операции.

Сопоставить читаемый снимок с реальной карточкой CUP

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

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

В собственной коллекции создаются CUP за 500 и LAMP за 1200. Один ограниченный Query получает CUP с полями sku/price без _id. Для одного сохранённого снимка отдельно проверяются primary, secondary и nearest.

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

$preference = new MongoDB\Driver\ReadPreference('secondary');
$readable = $snapshot->hasReadableServer($preference);
// Single с доступным Standalone не становится replica set из-за слова secondary.

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

Почему получился такой результат

Три строки таблицы — три проверки одного снимка, а не три обращения к разным репликам. Документ читается один раз. В Single доступный единственный Standalone подходит независимо от read preference; слово secondary не создаёт второй сервер. hasReadableServer получает необязательный объект ReadPreference, хотя на официальной странице в блоке параметров встречается ошибочная строка «параметров нет»; сигнатура содержит аргумент.

Ошибки и ограничения

При replica set правила выбора другие. Даже true не гарантирует свежесть прикладных данных, права на коллекцию или будущую доступность. Проверка не выполняет Query и не блокирует изменения топологии. Подходящий узел и корректный товар — два независимых условия, поэтому реальная операция всё равно требует обработки ошибок.

<?php
declare(strict_types=1);
require __DIR__.'/mt123-helper.php';
$runtime=mt123Runtime();
[$uri,$database]=mt123Config();
$journal=new Mt123Journal; $manager=null;
MongoDB\Driver\Monitoring\addSubscriber($journal);
try {
    $manager=mt123Manager($uri); mt123Ping($manager,$database); $snapshot=$journal->last();
    $documents=mt123WithCatalog($manager,$database,fn($namespace)=>mt123Products($manager,$namespace,['sku'=>'CUP'],1));
    $rows=[];
    foreach (['primary','secondary','nearest'] as $mode) {
        $readable=$snapshot->hasReadableServer(new MongoDB\Driver\ReadPreference($mode));
        $rows[]=[$mode,$snapshot->getType(),$readable,$documents[0]['sku'],$documents[0]['price']];
    }
    $checks=['bounded_actual_document'=>$documents===[['sku'=>'CUP','price'=>500]],
        'snapshot_writable'=>$snapshot->hasWritableServer(),'owned_collection_removed'=>true,
        'one_known_standalone'=>count($snapshot->getServers())===1 && $snapshot->getServers()[0]->getType()==='Standalone'];
} finally { unset($manager);MongoDB\Driver\Monitoring\removeSubscriber($journal); }
$details=['Полученная карточка'=>$documents,'Снимок'=>mt123Snapshot($snapshot),'Журнал'=>$journal->events,
    'Как читать строки'=>'Три вызова проверяют один снимок Single. Карточка CUP действительно запрошена один раз; три режима не означают три прочитанные реплики'];
$runtime['server']=mt123BuildVersion($uri,$database);
$expected=[['primary', 'Single', true, 'CUP', 500], ['secondary', 'Single', true, 'CUP', 500], ['nearest', 'Single', true, 'CUP', 500]];
$checks['expected_rows']=$rows===$expected;
mt123Report('mongodb123-topology-read-policy',['Политика снимка', 'Тип', 'Читаемый узел есть', 'Один реальный товар', 'Цена'],$rows,$checks,$runtime,$details);
echo 'mongodb123-topology-read-policy: OK',"\n";

mongodb123-topology-read-policy: OK

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

Упражнение и направление решения. Поменяйте фильтр sku на LAMP: единственный реальный документ должен содержать цену 1200, а три результата проверки того же доступного Single останутся true. Это показывает, что выбор документа и пригодность топологии — разные задачи.

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

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

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

Первый ping вызывает реальные события обнаружения. Из одного такого события сохраняются previousDescription с false и newDescription с true. Оба принадлежат одному topologyId. После сохранения значений выполняется второй ping.

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

$old = $event->getPreviousDescription();
$new = $event->getNewDescription();
$id = (string) $event->getTopologyId();
// Храним оба значения. Старый объект не превратится в $new после следующей команды.

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

Почему получился такой результат

TopologyDescription — неизменяемое описание, а не ссылка на постоянно обновляющуюся панель состояния. Программа не пытается получить его до первых событий. getPreviousDescription и getNewDescription дают точную пару конкретного события после первого обращения; номер клиента берётся через getTopologyId. Затем второй ping действительно выполняется, но сохранённый old остаётся прежним. В таблице видны его значения до и после второго обращения, а новое описание хранится отдельно.

Ошибки и ограничения

Previous означает непосредственно предыдущее описание данного события, а не обязательно первый снимок за жизнь приложения. Одного объекта A недостаточно для текущей диагностики через час. Журнал переходов в helper ограничен 16 записями; для долгого процесса нужна явная политика хранения истории, а не бесконечный массив.

<?php
declare(strict_types=1);
require __DIR__.'/mt123-helper.php';
$runtime=mt123Runtime();
[$uri,$database]=mt123Config();
$journal=new Mt123Journal; $manager=null;
MongoDB\Driver\Monitoring\addSubscriber($journal);
try {
    $manager=mt123Manager($uri); $ping=mt123Ping($manager,$database);
    $transition=null;
    foreach ($journal->changes as $change) {
        if ($change['old']->getType()==='Single' && !$change['old']->hasReadableServer()
            && $change['new']->hasReadableServer()) { $transition=$change; break; }
    }
    if ($transition===null) { throw new RuntimeException('Expected actual discovery transition'); }
    $saved=$transition['old'];$savedValue=mt123Snapshot($saved);$fresh=$transition['new'];
    $rows=[['Прежнее описание из события',$saved->getType(),$saved->hasReadableServer(),count($saved->getServers())]];
    $secondPing=mt123Ping($manager,$database);
    $rows[]=['Этот же объект после ещё одного ping',$saved->getType(),$saved->hasReadableServer(),count($saved->getServers())];
    $rows[]=['Новое описание из события',$fresh->getType(),$fresh->hasReadableServer(),count($fresh->getServers())];
    $checks=['real_ping'=>$ping && $secondPing,'old_snapshot_immutable'=>mt123Snapshot($saved)===$savedValue,
        'event_transition_actual'=>!$transition['old']->hasReadableServer() && $transition['new']->hasReadableServer(),
        'same_topology_identity'=>count(array_unique(array_column($journal->changes,'id')))===1];
} finally { unset($manager);MongoDB\Driver\Monitoring\removeSubscriber($journal); }
$details=['Переход события'=>['topologyId'=>$transition['id'],'before'=>mt123Snapshot($transition['old']),'after'=>mt123Snapshot($transition['new'])],
    'Старый снимок остаётся прежним'=>mt123Snapshot($saved),'Журнал'=>$journal->events,
    'Что не происходило'=>'Смена primary и отказ живого сервера не моделировались: это начальное обнаружение Standalone'];
$runtime['server']=mt123BuildVersion($uri,$database);
$expected=[['Прежнее описание из события', 'Single', false, 0], ['Этот же объект после ещё одного ping', 'Single', false, 0], ['Новое описание из события', 'Single', true, 1]];
$checks['expected_rows']=$rows===$expected;
mt123Report('mongodb123-topology-snapshot-history',['Какое значение', 'Тип', 'Читаемый узел', 'Описаний узлов'],$rows,$checks,$runtime,$details);
echo 'mongodb123-topology-snapshot-history: OK',"\n";

mongodb123-topology-snapshot-history: OK

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

Упражнение и направление решения. Сделайте две колонки отчёта old/new из одного TopologyChangedEvent. Не запрашивайте случайное текущее значение отдельно для колонки old. Если old=false и new=true, это в нашем случае обнаружение узла, не автоматическое доказательство восстановления после аварии.

Разделить события каталога и импорта на одном адресе

Один процесс использует MongoDB для каталога и импорта. Оба клиента ходят на один адрес, поэтому host:port не позволяет понять, к какой задаче относится событие. Разделим наблюдение по области регистрации и по идентификатору топологии.

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

Два независимых Manager с disableClientPersistence=true подключаются к одному стенду. Один журнал зарегистрирован глобально; для каталога есть второй, привязанный только к его Manager. Тот же глобальный объект дополнительно регистрируется в Manager и повторно добавляется: по контракту он не должен удваивать доставку.

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

MongoDB\Driver\Monitoring\addSubscriber($journal); // Все Manager процесса.
$catalog->addSubscriber($onlyCatalog);              // Только этот Manager.
$catalog->removeSubscriber($onlyCatalog);           // Снять эту регистрацию.
MongoDB\Driver\Monitoring\removeSubscriber($journal);

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

Почему получился такой результат

Глобальная регистрация действует на события расширения для любых Manager, а привязка к Manager ограничивает область наблюдения. Повторная регистрация того же объекта является no-op. Если он одновременно global и Manager-scoped, одно событие для данного Manager не доставляется дважды. Это проверяется сравнением heartbeat-счётчиков двух наблюдателей каталога. topologyId сохраняется в реальном журнале и связывается с именем задачи.

Ошибки и ограничения

Два объекта-подписчика с одинаковым кодом — не один и тот же объект: они могут законно получить одно событие каждый. topologyId относится к клиентской топологии, не к физическому кластеру или _id товара. Чтобы получить независимые клиенты здесь выключена persistence; обычное приложение может повторно использовать внутренний клиент. Снятие Manager-регистрации не снимает global-регистрацию того же объекта.

<?php
declare(strict_types=1);
require __DIR__.'/mt123-helper.php';
$runtime=mt123Runtime();
[$uri,$database]=mt123Config();
$global=new Mt123Journal; $onlyCatalog=new Mt123Journal; $catalog=null;$import=null;
MongoDB\Driver\Monitoring\addSubscriber($global);MongoDB\Driver\Monitoring\addSubscriber($global);
try {
    $catalog=mt123Manager($uri);
    $catalog->addSubscriber($global);$catalog->addSubscriber($global);
    $catalog->addSubscriber($onlyCatalog);$catalog->addSubscriber($onlyCatalog);
    $catalogOk=mt123Ping($catalog,$database);$catalogId=$global->openingIds[0];
    $deduplicated=$global->count('serverHeartbeatStarted')===$onlyCatalog->count('serverHeartbeatStarted')
        && $global->count('serverHeartbeatSucceeded')===$onlyCatalog->count('serverHeartbeatSucceeded');
    $scopeBefore=$onlyCatalog->counts;
    $catalog->removeSubscriber($onlyCatalog);$catalog->removeSubscriber($onlyCatalog);
    $import=mt123Manager($uri);$importOk=mt123Ping($import,$database);$importId=$global->openingIds[1];
    $catalog->removeSubscriber($global); // Global registration still exists.
    $rows=[['Глобальный журнал',count(array_unique($global->openingIds)),'каталог + импорт'],
        ['Подписчик Manager каталога',count($onlyCatalog->latest),'только каталог'],
        ['Один объект global + Manager',$deduplicated?'без удвоения':'есть дубли','одни heartbeat-уведомления']];
    $checks=['both_real_pings'=>$catalogOk && $importOk,'distinct_topology_ids'=>$catalogId!==$importId,
        'manager_scope_only_catalog'=>array_keys($onlyCatalog->latest)===[$catalogId],
        'removed_scope_unchanged'=>$scopeBefore===$onlyCatalog->counts,'duplicate_registration_noop'=>$deduplicated];
} finally {
    if ($catalog!==null) { $catalog->removeSubscriber($onlyCatalog);$catalog->removeSubscriber($global); }
    unset($catalog,$import);MongoDB\Driver\Monitoring\removeSubscriber($global);MongoDB\Driver\Monitoring\removeSubscriber($global);
}
$checks['both_global_closures']=count(array_unique($global->closedIds))===2;
$details=['Назначения клиентов'=>['каталог'=>$catalogId,'импорт'=>$importId],
    'Общий журнал'=>$global->events,'Журнал только каталога'=>$onlyCatalog->events,
    'Идентичность'=>'Один host:port, но два независимых непостоянных клиента. topologyId не является _id товара или идентификатором физического кластера'];
$runtime['server']=mt123BuildVersion($uri,$database);
$expected=[['Глобальный журнал', 2, 'каталог + импорт'], ['Подписчик Manager каталога', 1, 'только каталог'], ['Один объект global + Manager', 'без удвоения', 'одни heartbeat-уведомления']];
$checks['expected_rows']=$rows===$expected;
mt123Report('mongodb123-topology-two-clients',['Область наблюдения', 'Наблюдение', 'Что учтено'],$rows,$checks,$runtime,$details);
echo 'mongodb123-topology-two-clients: OK',"\n";

mongodb123-topology-two-clients: OK

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

Упражнение и направление решения. Нужно наблюдать только импорт. Зарегистрируйте отдельный объект через $import->addSubscriber и снимите его тем же Manager. Если оставить этот объект зарегистрированным глобально, ожидаемой изоляции не будет.

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

После unset($manager) разработчик ждёт сообщение о закрытии и не получает его. Покажем реальные условия такого события и отличие закрытия клиента от остановки базы.

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

Свежий Manager создаётся с driverOptions disableClientPersistence=true. Global-журнал зарегистрирован заранее. Короткий ping полностью прочитан внутри функции, её Cursor уже освобождён; других ссылок на Manager нет. Затем удаляется последняя ссылка на клиент.

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

$manager = new MongoDB\Driver\Manager($uri, [], ['disableClientPersistence'=>true]);
// После реальной команды освободить Cursor/Server/другие ссылки на клиент.
unset($manager); // Subscriber получает closure; mongod продолжает работать.

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

Почему получился такой результат

В таблице появляется одно закрытие, а последующий контрольный ping к тому же mongod успешен: закрыт клиент, не серверный процесс. Сохранённый до закрытия снимок продолжает сообщать true — потому что он историческое значение. Снятый global-подписчик больше не получает события контрольного клиента. Само событие topologyClosed доступно до request shutdown при отключённой persistence и реальном освобождении внутреннего клиента.

Ошибки и ограничения

При обычной persistence время жизни внутреннего клиента не обязано совпадать с переменной Manager. Cursor, Server или иные ссылки тоже могут удерживать клиент. Не вводите отключение persistence для каждого веб-запроса только ради красивого журнала: это отдельное изменение стратегии соединений. Callback закрытия не является командой shutdown MongoDB.

<?php
declare(strict_types=1);
require __DIR__.'/mt123-helper.php';
$runtime=mt123Runtime();
[$uri,$database]=mt123Config();
$journal=new Mt123Journal;$manager=null;
MongoDB\Driver\Monitoring\addSubscriber($journal);
try {
    $manager=mt123Manager($uri);$ping=mt123Ping($manager,$database);$connected=$journal->last();
    $beforeClosed=$journal->count('topologyClosed');
    unset($manager); // No Cursor or Server keeps the Manager alive.
    $afterClosed=$journal->count('topologyClosed');
    $rows=[['После ping',$journal->count('topologyOpening'),$beforeClosed,'клиент ещё существует'],
        ['После освобождения',count($journal->openingIds),$afterClosed,'клиент закрыт; сервер не остановлен']];
    $checks=['real_ping'=>$ping,'actual_lifecycle'=>$beforeClosed===0 && $afterClosed===1
        && $journal->count('serverClosed')===1 && $journal->count('serverOpening')===1,
        'same_open_close_id'=>$journal->openingIds===$journal->closedIds,
        'retained_snapshot_is_history'=>$connected->hasReadableServer() && $connected->hasWritableServer()];
} finally { unset($manager);MongoDB\Driver\Monitoring\removeSubscriber($journal); }
$countsAfterRemoval=$journal->counts;
$control=mt123Manager($uri);$stillAlive=mt123Ping($control,$database);unset($control);
$checks['server_still_running']=$stillAlive;
$checks['global_removal_effective']=$journal->counts===$countsAfterRemoval;
$details=['Настоящий жизненный цикл'=>$journal->events,'Счётчики'=>$journal->counts,
    'Снимок, сохранённый до закрытия'=>mt123Snapshot($connected),
    'Почему closure виден'=>'disableClientPersistence=true и освобождение клиента до завершения PHP request; обычная persistence имеет другую длительность жизни'];
$runtime['server']=mt123BuildVersion($uri,$database);
$expected=[['После ping', 1, 0, 'клиент ещё существует'], ['После освобождения', 1, 1, 'клиент закрыт; сервер не остановлен']];
$checks['expected_rows']=$rows===$expected;
mt123Report('mongodb123-topology-client-lifetime',['Момент', 'Открытий топологии', 'Закрытий топологии', 'Смысл'],$rows,$checks,$runtime,$details);
echo 'mongodb123-topology-client-lifetime: OK',"\n";

mongodb123-topology-client-lifetime: OK

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

Упражнение и направление решения. Объясните три разные операции: unset Manager освобождает PHP-ссылку; removeSubscriber снимает наблюдение; остановка mongod прекращает серверный процесс. В этом примере выполняются только первые две, а сервер остаётся доступным.

Практический вопрос: PHP Mongodb driver 1.5: how to use connection pool?. Автор не различает pooling и persistence текущего PHP-клиента и находит старые руководства. Наш пример объясняет ограниченное время жизни непостоянного клиента и настоящие closure-события; старые рецепты не копируются. Обсуждение использовано для постановки задачи; технические правила PHP-драйвера сверены по первичным источникам.

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

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

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

Программа занимает собственный случайный loopback-порт через STREAM_SERVER_BIND, не включая LISTEN. У тестового Manager connectTimeoutMS=300 и serverSelectionTimeoutMS=500. Установить MongoDB handshake с этим endpoint нельзя. После отказа отдельно проверяется настоящий здоровый стенд.

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

public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent $event): void {
    $this->failures++; // Сигнал наблюдения, а не результат пользовательского запроса.
}
// Исключение самой операции всё равно обрабатывается вокруг executeReadCommand.

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

Почему получился такой результат

В журнале находятся события, реально присланные драйвером. Исключение самой операции ловится отдельно: запись failed heartbeat не заменяет catch вокруг executeReadCommand. После сохранения имени класса исключение освобождается через unset($error): его стек может удерживать Manager и откладывать закрытие клиента. Тип Single остаётся способом подключения, но читаемого/writable узла в снимке нет. Реальный номер временного порта и длительность heartbeat выводятся в подробностях; они не закрепляются как постоянные значения.

Ошибки и ограничения

Опыт проверяет отказ начального handshake на собственном endpoint. Он не моделирует потерю данных, падение replica set, отказ любого конкретного production-сервера или автоматический retry записи. Указанные таймауты ограничивают соответствующие стадии драйвера, но не служат обещанием ровно 500 мс по внешним часам. В рабочем журнале сокращайте чувствительные данные и не выводите URI с паролем.

<?php
declare(strict_types=1);
require __DIR__.'/mt123-helper.php';
$runtime=mt123Runtime();
[$uri,$database]=mt123Config();
$journal=new Mt123Journal;$failed=null;$bound=null;$errorClass=null;
[$bound,$failureUri]=mt123BoundFailure();
MongoDB\Driver\Monitoring\addSubscriber($journal);
try {
    $failed=mt123Manager($failureUri,true);
    try { mt123Ping($failed,$database); }
    catch (MongoDB\Driver\Exception\ConnectionException $error) { $errorClass=get_class($error); unset($error); }
    $snapshot=$journal->last();
    $rows=[['Проверяемый недоступный endpoint',$snapshot->getType(),$snapshot->hasReadableServer(),$snapshot->hasWritableServer(),'исключение соединения'],
        ['Реальный heartbeat',$journal->count('serverHeartbeatStarted')>0?'начат':'не начат',
            $journal->count('serverHeartbeatFailed')>0,false,'отказ записан в журнал']];
    $checks=['real_connection_error'=>$errorClass!==null,'real_failed_heartbeat'=>$journal->count('serverHeartbeatFailed')>=1
            && $journal->count('serverHeartbeatStarted')>=$journal->count('serverHeartbeatFailed'),
        'snapshot_unavailable'=>!$snapshot->hasReadableServer() && !$snapshot->hasWritableServer(),
        'no_false_heartbeat_success'=>$journal->count('serverHeartbeatSucceeded')===0];
} finally {
    unset($failed);MongoDB\Driver\Monitoring\removeSubscriber($journal);
    if (is_resource($bound)) { fclose($bound); }
}
$checks['failed_client_closed']=$journal->count('topologyClosed')===1 && $journal->count('serverClosed')===1;
$control=mt123Manager($uri);$checks['healthy_control_ping']=mt123Ping($control,$database);unset($control);
$details=['Фактическая ошибка операции'=>$errorClass,'Фактический журнал отказа'=>$journal->events,
    'Тестовый endpoint'=>$failureUri,'Снимок отказа'=>mt123Snapshot($snapshot),
    'Ограничение'=>'Своя зарезервированная loopback-точка не слушает. Настоящий MongoDB не останавливался; последующий контрольный ping успешен'];
$runtime['server']=mt123BuildVersion($uri,$database);
$expected=[['Проверяемый недоступный endpoint', 'Single', false, false, 'исключение соединения'], ['Реальный heartbeat', 'начат', true, false, 'отказ записан в журнал']];
$checks['expected_rows']=$rows===$expected;
mt123Report('mongodb123-topology-heartbeat-failure',['Наблюдение', 'Тип или этап', 'Чтение / отказ замечен', 'Запись доступна', 'Вывод'],$rows,$checks,$runtime,$details);
echo 'mongodb123-topology-heartbeat-failure: OK',"\n";

mongodb123-topology-heartbeat-failure: OK

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

Упражнение и направление решения. Найдите в полном коде две независимые проверки: наличие serverHeartbeatFailed и класс исключения операции. Успешное прохождение одной не позволяет автоматически выдумать результат другой. Сокет и клиент освобождаются в finally.

Практический вопрос: Cannot connect to MongoDB: server selection timed out. После перезапуска компьютера локальный endpoint не отвечает, хотя в диагностике показан Single. Пример отделяет тип топологии от доступности и собирает реальные started/failed события на собственном контролируемом endpoint. Обсуждение использовано для постановки задачи; технические правила PHP-драйвера сверены по первичным источникам.

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

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

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

Первая точка — собственный non-listening сокет, вторая — существующий локальный MongoDB. После реального исключения первого ping приложение создаёт второй Manager и выполняет отдельный ping. Global-журнал сохраняет оба topologyId.

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

try { $ok = mt123Ping($candidate, $database); }
catch (MongoDB\Driver\Exception\ConnectionException $error) {
    // После сообщения об отказе явно выбираем разрешённый диагностический стенд.
    $ok = mt123Ping($knownLab, $database);
} // Это политика программы для ping, не автоматический повтор записи.

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

Почему получился такой результат

Успех второй операции не исправляет исторический снимок первого клиента. Разные topologyId позволяют показать, где была ошибка и что именно проверено затем. Перед закрытием первого клиента сохраняется только имя класса ошибки, а объект исключения освобождается: его стек может удерживать Manager. В журнале видны и настоящий failed heartbeat, и successful heartbeat. Нет остановки базы, автоматического выбора нового primary или незаметного повторения пользовательской записи.

Ошибки и ограничения

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

<?php
declare(strict_types=1);
require __DIR__.'/mt123-helper.php';
$runtime=mt123Runtime();
[$uri,$database]=mt123Config();
$journal=new Mt123Journal;$failed=null;$healthy=null;$bound=null;$errorClass=null;
[$bound,$failureUri]=mt123BoundFailure();
MongoDB\Driver\Monitoring\addSubscriber($journal);
try {
    $failed=mt123Manager($failureUri,true);
    try { mt123Ping($failed,$database); }
    catch (MongoDB\Driver\Exception\ConnectionException $error) { $errorClass=get_class($error); unset($error); }
    $failedSnapshot=$journal->last();$failedId=$journal->openingIds[0];unset($failed);
    if ($errorClass===null) { throw new RuntimeException('Expected explicit test endpoint failure'); }
    $healthy=mt123Manager($uri);$ok=mt123Ping($healthy,$database);$healthySnapshot=$journal->last();$healthyId=$journal->openingIds[1];
    $rows=[['Проверяемая точка',$failedSnapshot->hasReadableServer(),$failedSnapshot->hasWritableServer(),'показать отказ проверки'],
        ['Заранее известный локальный стенд',$healthySnapshot->hasReadableServer(),$healthySnapshot->hasWritableServer(),'явно проверить другой клиент']];
    $checks=['actual_failure_and_success'=>$errorClass!==null && $ok,'two_client_identities'=>$failedId!==$healthyId,
        'both_real_heartbeat_outcomes'=>$journal->count('serverHeartbeatFailed')>=1 && $journal->count('serverHeartbeatSucceeded')>=1,
        'failed_history_unchanged'=>!$failedSnapshot->hasReadableServer() && $healthySnapshot->hasReadableServer()];
} finally { unset($failed,$healthy);MongoDB\Driver\Monitoring\removeSubscriber($journal);if(is_resource($bound)){fclose($bound);} }
$checks['both_clients_closed']=count(array_unique($journal->closedIds))===2;
$details=['Связь имён с topologyId'=>['проверяемая точка'=>$failedId,'здоровый стенд'=>$healthyId],
    'Журнал двух разных клиентов'=>$journal->events,'Ошибка первой операции'=>$errorClass,
    'Политика приложения'=>'После отказа только диагностического ping явно проверяется отдельный известный стенд. Это не retry записи, не запасная копия данных и не автоматический failover replica set'];
$runtime['server']=mt123BuildVersion($uri,$database);
$expected=[['Проверяемая точка', false, false, 'показать отказ проверки'], ['Заранее известный локальный стенд', true, true, 'явно проверить другой клиент']];
$checks['expected_rows']=$rows===$expected;
mt123Report('mongodb123-topology-explicit-fallback',['Шаг приложения', 'Чтение в снимке', 'Запись в снимке', 'Явное действие'],$rows,$checks,$runtime,$details);
echo 'mongodb123-topology-explicit-fallback: OK',"\n";

mongodb123-topology-explicit-fallback: OK

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

Упражнение и направление решения. Почему нельзя назвать вторую строку «первая база восстановилась»? Потому что создан другой клиент с другим endpoint и topologyId. Отчёт должен прямо называть выполненное действие: проверен отдельный известный стенд.

Практический вопрос: MongoDB Atlas connections time out. Сообщения служебного monitor-потока принимаются за обязательный отказ каждой операции приложения. Наши два клиента позволяют раздельно показать отказ heartbeat, исключение первой операции и успех другой явно выполненной проверки, без обещаний автоматического failover. Обсуждение использовано для постановки задачи; технические правила PHP-драйвера сверены по первичным источникам.

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

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

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

Первое задание читает экран CUP/LAMP с двумя нужными полями и limit=2, второе — одну карточку LAMP. У каждого собственная учебная коллекция и свой scoped-подписчик. Общий журнал сохраняет только первые шесть записей, но продолжает считать типы событий.

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

if (count($this->events) < $this->limit) {
    $this->events[] = $record;
} else {
    ++$this->discarded;
} // Общий счётчик события увеличивается до этой проверки.

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

Почему получился такой результат

Результат задач — реальные артикулы, а не один счётчик событий. После переполнения буфера программа не притворяется, что журнал полный: discarded увеличивается. Проверяется равенство общей суммы событий сохранённым плюс отброшенным. Scoped-подписчик снимается в finally задания; глобальный остаётся до закрытия клиентов, затем тоже снимается. Контрольный клиент уже не меняет его счётчики.

Ошибки и ограничения

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

<?php
declare(strict_types=1);
require __DIR__.'/mt123-helper.php';
$runtime=mt123Runtime();
[$uri,$database]=mt123Config();
$journal=new Mt123Journal(6);$worker=null;$scoped=null;$results=[];$scopeChecks=[];
MongoDB\Driver\Monitoring\addSubscriber($journal);
try {
    foreach (['экран каталога','карточка LAMP'] as $position=>$job) {
        $worker=mt123Manager($uri);$scoped=new Mt123Journal;
        $worker->addSubscriber($scoped);$worker->addSubscriber($scoped);
        try {
            $documents=mt123WithCatalog($worker,$database,fn($namespace)=>mt123Products($worker,$namespace,$position===0?[]:['sku'=>'LAMP'],$position===0?2:1));
            $results[]=['job'=>$job,'documents'=>$documents];
        } finally { $worker->removeSubscriber($scoped);$worker->removeSubscriber($scoped); }
        $scopeCounts=$scoped->counts;unset($worker);$worker=null;
        $scopeChecks[]=$scoped->counts===$scopeCounts && $scoped->count('serverHeartbeatSucceeded')>=1;
    }
} finally {
    if ($worker!==null && $scoped!==null) { $worker->removeSubscriber($scoped); }
    unset($worker);MongoDB\Driver\Monitoring\removeSubscriber($journal);
}
$frozenCounts=$journal->counts;
$quiet=mt123Manager($uri);$quietOk=mt123Ping($quiet,$database);unset($quiet);
$rows=[];
foreach($results as $item){$rows[]=[$item['job'],implode(', ',array_column($item['documents'],'sku')),count($item['documents'])];}
$checks=['actual_two_screens'=>$results[0]['documents']===[['sku'=>'CUP','price'=>500],['sku'=>'LAMP','price'=>1200]]
        && $results[1]['documents']===[['sku'=>'LAMP','price'=>1200]],
    'owned_collections_removed'=>true,'bounded_buffer'=>count($journal->events)===6 && $journal->discarded>0,
    'counts_preserved'=>array_sum($journal->counts)===count($journal->events)+$journal->discarded,
    'manager_removal_effective'=>!in_array(false,$scopeChecks,true),'global_removal_effective'=>$journal->counts===$frozenCounts && $quietOk,
    'real_two_closed_clients'=>count(array_unique($journal->closedIds))===2 && $journal->count('serverClosed')===2];
$details=['Сохранено первых записей'=>count($journal->events),'Пропущено после лимита'=>$journal->discarded,
    'Ограниченный журнал'=>$journal->events,'Полные счётчики по именам'=>$journal->counts,
    'topologyId закрытых заданий'=>$journal->closedIds,'Полученные экраны'=>$results,
    'Ограничение'=>'Буфер показывает начало, а не полную историю инцидента. В производстве нужны согласованные хранение/ротация/доставка; callback не должен делать блокирующий сетевой запрос'];
$runtime['server']=mt123BuildVersion($uri,$database);
$expected=[['экран каталога', 'CUP, LAMP', 2], ['карточка LAMP', 'LAMP', 1]];
$checks['expected_rows']=$rows===$expected;
mt123Report('mongodb123-topology-bounded-worker',['Задание', 'Реальные артикулы', 'Строк'],$rows,$checks,$runtime,$details);
echo 'mongodb123-topology-bounded-worker: OK',"\n";

mongodb123-topology-bounded-worker: OK

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

Упражнение и направление решения. Поменяйте лимит 6 на 12 и сравните только число сохранённых/отброшенных записей, не придумывая неизменное число heartbeat. Сумма counts должна по-прежнему равняться saved+discarded. Полезные две таблицы товаров не должны измениться из-за размера журнала.

Снимки, события, девять callbacks и четыре способа регистрации

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

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

Полезный журнал отвечает на три вопроса: какому клиенту относится событие, что действительно изменилось в его описании и что получила сама прикладная операция. Сохраняйте точную пару old/new и topologyId, ограничивайте память, снимайте подписки по окончании области работы. Исторический true у снимка и successful heartbeat не отменяют обработку отказа следующего чтения или записи.

Следующие шаги: подробности ServerDescription и ServerChangedEvent, default-настройки Manager и фактический Server ответа, жизненный цикл Cursor, согласованность и выбор на replica set. Для диагностики бизнес-операций отдельно нужны их результаты и ошибки: квитанция пакетной записи и частичные отказы.