Add documentation

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
+...

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
+...

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

docs/reference/method/MongoDBClient-addSubscriber.txt

@@ -0,0 +1,130 @@
+================================
+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
+
+    <?php
+
+        use MongoDB\Driver\Monitoring\CommandSubscriber;
+        use MongoDB\Driver\Monitoring\CommandStartedEvent;
+        use MongoDB\Driver\Monitoring\CommandSucceededEvent;
+        use MongoDB\Driver\Monitoring\CommandFailedEvent;
+
+        class LogCommandSubscriber implements CommandSubscriber
+        {
+            private $stream;
+            public function __construct($stream)
+            {
+                $this->stream = $stream;
+            }
+
+            public function commandStarted(CommandStartedEvent $event): void
+            {
+                fwrite($this->stream, sprintf(
+                    'Started command #%d "%s": %s%s',
+                    $event->getRequestId(),
+                    $event->getCommandName(),
+                    Document::fromPHP($event->getCommand())->toCanonicalExtendedJSON(),
+                    PHP_EOL,
+                ));
+            }
+
+            public function commandSucceeded(CommandSucceededEvent $event): void
+            {
+                fwrite($this->stream, 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($this->stream, 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
+
+    <?php
+
+        $client = new MongoDB\Client();
+        $subscriber = new LogCommandSubscriber(STDERR);
+
+        $client->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)
+  <manual/en/mongodb.tutorial.apm>`
+- :php:`MongoDB\\Driver\\Manager::addSubscriber()
+  <manual/en/mongodb-driver-manager.addsubscriber>`
+- :php:`MongoDB\Driver\Monitoring\Subscriber
+  <manual/en/class.mongodb-driver-monitoring-subscriber>`
+- :php:`MongoDB\Driver\Monitoring\CommandSubscriber
+  <manual/en/class.mongodb-driver-monitoring-commandsubscriber>`

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)
+  <manual/en/mongodb.tutorial.apm>`
+- :php:`MongoDB\\Driver\\Manager::removeSubscriber()
+  <manual/en/mongodb-driver-manager.addsubscriber>`
+- :php:`MongoDB\Driver\Monitoring\Subscriber
+  <manual/en/class.mongodb-driver-monitoring-subscriber>`
+- :php:`MongoDB\Driver\Monitoring\CommandSubscriber
+  <manual/en/class.mongodb-driver-monitoring-commandsubscriber>`