Skip to content

Commit 0382eb8

Browse files
GromNaNGromNaN
committed
Add documentation
1 parent 167bf9a commit 0382eb8

5 files changed

+193
-0
lines changed

‎docs/includes/apiargs-MongoDBClient-method-addSubscriber-param.yaml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
arg_name: param
2+
name: $subscriber
3+
type: MongoDB\Driver\Monitoring\Subscriber
4+
description: |
5+
A monitoring event subscriber to register with this Client.
6+
interface: phpmethod
7+
operation: ~
8+
optional: false
9+
...

‎docs/includes/apiargs-MongoDBClient-method-removeSubscriber-param.yaml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
arg_name: param
2+
name: $subscriber
3+
type: MongoDB\Driver\Monitoring\Subscriber
4+
description: |
5+
A monitoring event subscriber to register with this Client.
6+
interface: phpmethod
7+
operation: ~
8+
optional: false
9+
...

‎docs/reference/class/MongoDBClient.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Methods
3030

3131
/reference/method/MongoDBClient__construct
3232
/reference/method/MongoDBClient__get
33+
/reference/method/MongoDBClient-addSubscriber
3334
/reference/method/MongoDBClient-createClientEncryption
3435
/reference/method/MongoDBClient-dropDatabase
3536
/reference/method/MongoDBClient-getManager
@@ -39,6 +40,7 @@ Methods
3940
/reference/method/MongoDBClient-getWriteConcern
4041
/reference/method/MongoDBClient-listDatabaseNames
4142
/reference/method/MongoDBClient-listDatabases
43+
/reference/method/MongoDBClient-removeSubscriber
4244
/reference/method/MongoDBClient-selectCollection
4345
/reference/method/MongoDBClient-selectDatabase
4446
/reference/method/MongoDBClient-startSession

‎docs/reference/method/MongoDBClient-addSubscriber.txt

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
================================
2+
MongoDB\\Client::addSubscriber()
3+
================================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. phpmethod:: MongoDB\\Client::addSubscriber()
17+
18+
Registers a monitoring event subscriber with this Client. The subscriber
19+
will be notified of all events for this Client.
20+
21+
.. code-block:: php
22+
23+
function addSubscriber(MongoDB\Driver\Monitoring\Subscriber $subscriber): void
24+
25+
This method has the following parameters:
26+
27+
.. include:: /includes/apiargs/MongoDBClient-method-addSubscriber-param.rst
28+
29+
.. note::
30+
31+
If $subscriber is already registered with this Client, this function
32+
is a no-op. If $subscriber is also registered globally, it will still
33+
only be notified once of each event for this Client.
34+
35+
Errors/Exceptions
36+
-----------------
37+
38+
.. include:: /includes/extracts/error-invalidargumentexception.rst
39+
40+
Example
41+
-------
42+
43+
Create a :phpclass:`MongoDB\\Driver\\Monitoring\\CommandSubscriber` that
44+
logs all events:
45+
46+
.. code-block:: php
47+
48+
<?php
49+
50+
use MongoDB\Driver\Monitoring\CommandSubscriber;
51+
use MongoDB\Driver\Monitoring\CommandStartedEvent;
52+
use MongoDB\Driver\Monitoring\CommandSucceededEvent;
53+
use MongoDB\Driver\Monitoring\CommandFailedEvent;
54+
55+
class LogCommandSubscriber implements CommandSubscriber
56+
{
57+
public function commandStarted(CommandStartedEvent $event): void
58+
{
59+
fwrite(STDERR, sprintf(
60+
'Started command #%d "%s": %s%s',
61+
$event->getRequestId(),
62+
$event->getCommandName(),
63+
Document::fromPHP($event->getCommand())->toCanonicalExtendedJSON(),
64+
PHP_EOL,
65+
));
66+
}
67+
68+
public function commandSucceeded(CommandSucceededEvent $event): void
69+
{
70+
fwrite(STDERR, sprintf(
71+
'Succeeded command #%d "%s" in %d microseconds: %s%s',
72+
$event->getRequestId(),
73+
$event->getCommandName(),
74+
$event->getDurationMicros(),
75+
json_encode($event->getReply()),
76+
PHP_EOL,
77+
));
78+
}
79+
80+
public function commandFailed(CommandFailedEvent $event): void
81+
{
82+
fwrite(STDERR, sprintf(
83+
'Failed command #%d "%s" in %d microseconds: %s%s',
84+
$event->getRequestId(),
85+
$event->getCommandName(),
86+
$event->getDurationMicros(),
87+
$event->getError()->getMessage(),
88+
PHP_EOL,
89+
));
90+
}
91+
}
92+
93+
The subscriber can then be registered with a Client:
94+
95+
.. code-block:: php
96+
97+
<?php
98+
99+
$client = new MongoDB\Client();
100+
$subscriber = new LogCommandSubscriber(STDERR);
101+
102+
$client->addSubscriber($subscriber);
103+
104+
$client->test->users->insertOne(['username' => 'alice']);
105+
106+
The above code will log the following to err output:
107+
108+
.. code-block:: text
109+
110+
Started command #1 "insert": { "insert" : "users", "ordered" : true, "$db" : "test", "lsid" : { "id" : { "$binary" : { "base64" : "dKTBhZD7Qvi0vUhvR58mCA==", "subType" : "04" } } }, "documents" : [ { "username" : "alice", "_id" : { "$oid" : "655d1fca12e81018340a4fc2" } } ] }
111+
Succeeded command #1 "insert" in 3349 microseconds: {"n":1,"ok":1}
112+
113+
See Also
114+
--------
115+
116+
- :phpmethod:`MongoDB\\Client::removeSubscriber()`
117+
- :php:`Application Performance Monitoring (APM)
118+
<manual/en/mongodb.tutorial.apm>`
119+
- :php:`MongoDB\\Driver\\Manager::addSubscriber()
120+
<manual/en/mongodb-driver-manager.addsubscriber>`
121+
- :php:`MongoDB\Driver\Monitoring\Subscriber
122+
<manual/en/class.mongodb-driver-monitoring-subscriber>`
123+
- :php:`MongoDB\Driver\Monitoring\CommandSubscriber
124+
<manual/en/class.mongodb-driver-monitoring-commandsubscriber>`

‎docs/reference/method/MongoDBClient-removeSubscriber.txt

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
================================
2+
MongoDB\\Client::removeSubscriber()
3+
================================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. phpmethod:: MongoDB\\Client::removeSubscriber()
17+
18+
Unregisters a monitoring event subscriber with this Client.
19+
20+
.. code-block:: php
21+
22+
function removeSubscriber(MongoDB\Driver\Monitoring\Subscriber $subscriber): void
23+
24+
This method has the following parameters:
25+
26+
.. include:: /includes/apiargs/MongoDBClient-method-removeSubscriber-param.rst
27+
28+
.. note::
29+
30+
If $subscriber is not registered with this Client, this function
31+
is a no-op.
32+
33+
Errors/Exceptions
34+
-----------------
35+
36+
.. include:: /includes/extracts/error-invalidargumentexception.rst
37+
38+
See Also
39+
--------
40+
41+
- :phpmethod:`MongoDB\\Client::addSubscriber()`
42+
- :php:`Application Performance Monitoring (APM)
43+
<manual/en/mongodb.tutorial.apm>`
44+
- :php:`MongoDB\\Driver\\Manager::removeSubscriber()
45+
<manual/en/mongodb-driver-manager.addsubscriber>`
46+
- :php:`MongoDB\Driver\Monitoring\Subscriber
47+
<manual/en/class.mongodb-driver-monitoring-subscriber>`
48+
- :php:`MongoDB\Driver\Monitoring\CommandSubscriber
49+
<manual/en/class.mongodb-driver-monitoring-commandsubscriber>`

0 commit comments

Comments
 (0)