Skip to content

Commit 0361e42

Browse files
GromNaNGromNaN
committed
Add documentation
1 parent 167bf9a commit 0361e42

5 files changed

+199
-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: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
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+
private $stream;
58+
public function __construct($stream)
59+
{
60+
$this->stream = $stream;
61+
}
62+
63+
public function commandStarted(CommandStartedEvent $event): void
64+
{
65+
fwrite($this->stream, sprintf(
66+
'Started command #%d "%s": %s%s',
67+
$event->getRequestId(),
68+
$event->getCommandName(),
69+
Document::fromPHP($event->getCommand())->toCanonicalExtendedJSON(),
70+
PHP_EOL,
71+
));
72+
}
73+
74+
public function commandSucceeded(CommandSucceededEvent $event): void
75+
{
76+
fwrite($this->stream, sprintf(
77+
'Succeeded command #%d "%s" in %d microseconds: %s%s',
78+
$event->getRequestId(),
79+
$event->getCommandName(),
80+
$event->getDurationMicros(),
81+
json_encode($event->getReply()),
82+
PHP_EOL,
83+
));
84+
}
85+
86+
public function commandFailed(CommandFailedEvent $event): void
87+
{
88+
fwrite($this->stream, sprintf(
89+
'Failed command #%d "%s" in %d microseconds: %s%s',
90+
$event->getRequestId(),
91+
$event->getCommandName(),
92+
$event->getDurationMicros(),
93+
$event->getError()->getMessage(),
94+
PHP_EOL,
95+
));
96+
}
97+
}
98+
99+
The subscriber can then be registered with a Client:
100+
101+
.. code-block:: php
102+
103+
<?php
104+
105+
$client = new MongoDB\Client();
106+
$subscriber = new LogCommandSubscriber(STDERR);
107+
108+
$client->addSubscriber($subscriber);
109+
110+
$client->test->users->insertOne(['username' => 'alice']);
111+
112+
The above code will log the following to err output:
113+
114+
.. code-block:: text
115+
116+
Started command #1 "insert": { "insert" : "users", "ordered" : true, "$db" : "test", "lsid" : { "id" : { "$binary" : { "base64" : "dKTBhZD7Qvi0vUhvR58mCA==", "subType" : "04" } } }, "documents" : [ { "username" : "alice", "_id" : { "$oid" : "655d1fca12e81018340a4fc2" } } ] }
117+
Succeeded command #1 "insert" in 3349 microseconds: {"n":1,"ok":1}
118+
119+
See Also
120+
--------
121+
122+
- :phpmethod:`MongoDB\\Client::removeSubscriber()`
123+
- :php:`Application Performance Monitoring (APM)
124+
<manual/en/mongodb.tutorial.apm>`
125+
- :php:`MongoDB\\Driver\\Manager::addSubscriber()
126+
<manual/en/mongodb-driver-manager.addsubscriber>`
127+
- :php:`MongoDB\Driver\Monitoring\Subscriber
128+
<manual/en/class.mongodb-driver-monitoring-subscriber>`
129+
- :php:`MongoDB\Driver\Monitoring\CommandSubscriber
130+
<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)