diff --git a/docs/includes/apiargs-MongoDBClient-method-addSubscriber-param.yaml b/docs/includes/apiargs-MongoDBClient-method-addSubscriber-param.yaml new file mode 100644 index 000000000..22c9fb09c --- /dev/null +++ b/docs/includes/apiargs-MongoDBClient-method-addSubscriber-param.yaml @@ -0,0 +1,9 @@ +arg_name: param +name: $subscriber +type: MongoDB\Driver\Monitoring\Subscriber +description: | + A monitoring event subscriber to register with this Client. +interface: phpmethod +operation: ~ +optional: false +... diff --git a/docs/includes/apiargs-MongoDBClient-method-removeSubscriber-param.yaml b/docs/includes/apiargs-MongoDBClient-method-removeSubscriber-param.yaml new file mode 100644 index 000000000..22c9fb09c --- /dev/null +++ b/docs/includes/apiargs-MongoDBClient-method-removeSubscriber-param.yaml @@ -0,0 +1,9 @@ +arg_name: param +name: $subscriber +type: MongoDB\Driver\Monitoring\Subscriber +description: | + A monitoring event subscriber to register with this Client. +interface: phpmethod +operation: ~ +optional: false +... diff --git a/docs/reference/class/MongoDBClient.txt b/docs/reference/class/MongoDBClient.txt index b677ebb1d..654a474a5 100644 --- a/docs/reference/class/MongoDBClient.txt +++ b/docs/reference/class/MongoDBClient.txt @@ -30,6 +30,7 @@ Methods /reference/method/MongoDBClient__construct /reference/method/MongoDBClient__get + /reference/method/MongoDBClient-addSubscriber /reference/method/MongoDBClient-createClientEncryption /reference/method/MongoDBClient-dropDatabase /reference/method/MongoDBClient-getManager @@ -39,6 +40,7 @@ Methods /reference/method/MongoDBClient-getWriteConcern /reference/method/MongoDBClient-listDatabaseNames /reference/method/MongoDBClient-listDatabases + /reference/method/MongoDBClient-removeSubscriber /reference/method/MongoDBClient-selectCollection /reference/method/MongoDBClient-selectDatabase /reference/method/MongoDBClient-startSession diff --git a/docs/reference/method/MongoDBClient-addSubscriber.txt b/docs/reference/method/MongoDBClient-addSubscriber.txt new file mode 100644 index 000000000..46709ee93 --- /dev/null +++ b/docs/reference/method/MongoDBClient-addSubscriber.txt @@ -0,0 +1,124 @@ +================================ +MongoDB\\Client::addSubscriber() +================================ + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Definition +---------- + +.. phpmethod:: MongoDB\\Client::addSubscriber() + + Registers a monitoring event subscriber with this Client. The subscriber + will be notified of all events for this Client. + + .. code-block:: php + + function addSubscriber(MongoDB\Driver\Monitoring\Subscriber $subscriber): void + + This method has the following parameters: + + .. include:: /includes/apiargs/MongoDBClient-method-addSubscriber-param.rst + + .. note:: + + If $subscriber is already registered with this Client, this function + is a no-op. If $subscriber is also registered globally, it will still + only be notified once of each event for this Client. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-invalidargumentexception.rst + +Example +------- + +Create a :phpclass:`MongoDB\\Driver\\Monitoring\\CommandSubscriber` that +logs all events: + +.. code-block:: php + + getRequestId(), + $event->getCommandName(), + Document::fromPHP($event->getCommand())->toCanonicalExtendedJSON(), + PHP_EOL, + )); + } + + public function commandSucceeded(CommandSucceededEvent $event): void + { + fwrite(STDERR, sprintf( + 'Succeeded command #%d "%s" in %d microseconds: %s%s', + $event->getRequestId(), + $event->getCommandName(), + $event->getDurationMicros(), + json_encode($event->getReply()), + PHP_EOL, + )); + } + + public function commandFailed(CommandFailedEvent $event): void + { + fwrite(STDERR, sprintf( + 'Failed command #%d "%s" in %d microseconds: %s%s', + $event->getRequestId(), + $event->getCommandName(), + $event->getDurationMicros(), + $event->getError()->getMessage(), + PHP_EOL, + )); + } + } + +The subscriber can then be registered with a Client: + +.. code-block:: php + + addSubscriber($subscriber); + + $client->test->users->insertOne(['username' => 'alice']); + +The above code will log the following to err output: + +.. code-block:: text + + Started command #1 "insert": { "insert" : "users", "ordered" : true, "$db" : "test", "lsid" : { "id" : { "$binary" : { "base64" : "dKTBhZD7Qvi0vUhvR58mCA==", "subType" : "04" } } }, "documents" : [ { "username" : "alice", "_id" : { "$oid" : "655d1fca12e81018340a4fc2" } } ] } + Succeeded command #1 "insert" in 3349 microseconds: {"n":1,"ok":1} + +See Also +-------- + +- :phpmethod:`MongoDB\\Client::removeSubscriber()` +- :php:`Application Performance Monitoring (APM) + ` +- :php:`MongoDB\\Driver\\Manager::addSubscriber() + ` +- :php:`MongoDB\Driver\Monitoring\Subscriber + ` +- :php:`MongoDB\Driver\Monitoring\CommandSubscriber + ` diff --git a/docs/reference/method/MongoDBClient-removeSubscriber.txt b/docs/reference/method/MongoDBClient-removeSubscriber.txt new file mode 100644 index 000000000..2b2249b87 --- /dev/null +++ b/docs/reference/method/MongoDBClient-removeSubscriber.txt @@ -0,0 +1,49 @@ +================================ +MongoDB\\Client::removeSubscriber() +================================ + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Definition +---------- + +.. phpmethod:: MongoDB\\Client::removeSubscriber() + + Unregisters a monitoring event subscriber with this Client. + + .. code-block:: php + + function removeSubscriber(MongoDB\Driver\Monitoring\Subscriber $subscriber): void + + This method has the following parameters: + + .. include:: /includes/apiargs/MongoDBClient-method-removeSubscriber-param.rst + + .. note:: + + If $subscriber is not registered with this Client, this function + is a no-op. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-invalidargumentexception.rst + +See Also +-------- + +- :phpmethod:`MongoDB\\Client::addSubscriber()` +- :php:`Application Performance Monitoring (APM) + ` +- :php:`MongoDB\\Driver\\Manager::removeSubscriber() + ` +- :php:`MongoDB\Driver\Monitoring\Subscriber + ` +- :php:`MongoDB\Driver\Monitoring\CommandSubscriber + `