Skip to content

Commit 8d1f9ac

Browse files
jmikolajmikola
committed
Replace apiargs for Client methods
1 parent 8fa9cc6 commit 8d1f9ac

21 files changed

+661
-59
lines changed

‎docs/includes/option-collation.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
:manual:`Collation </reference/collation>` allows users to specify
2+
language-specific rules for string comparison, such as rules for lettercase
3+
and accent marks. When specifying collation, the ``locale`` field is mandatory;
4+
all other collation fields are optional. For descriptions of the fields,
5+
see :manual:`Collation Document </reference/collation/#collation-document>`.

‎docs/includes/option-comment.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Enables users to specify an arbitrary comment to help trace the operation
2+
through the :manual:`database profiler </reference/database-profiler>`,
3+
:manual:`currentOp </reference/command/currentOp>` output, and
4+
:manual:`logs </reference/log-messages>`.

‎docs/includes/option-maxTimeMS.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
The cumulative time limit in milliseconds for processing operations on the
2+
cursor. MongoDB aborts the operation at the earliest following
3+
:term:`interrupt point`.

‎docs/includes/option-readConcern.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
:manual:`Read concern </reference/read-concern>` to use for the operation.
2+
Defaults to the |parent|'s read concern.

‎docs/includes/option-readPreference.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
:manual:`Read preference </reference/read-preference>` to use for the operation.
2+
Defaults to the |parent|'s read preference.

‎docs/includes/option-session.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Client session to associate with the operation.

‎docs/includes/option-typeMap.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
The :php:`type map <manual/en/mongodb.persistence.deserialization.php#mongodb.persistence.typemaps>`
2+
to apply to cursors, which determines how BSON documents are converted to PHP
3+
values. Defaults to the |parent|'s type map.

‎docs/includes/option-writeConcern.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
:manual:`Write concern </reference/write-concern>` to use for the operation.
2+
Defaults to the |parent|'s write concern.

‎docs/includes/watch-options.rst

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
.. list-table::
2+
:header-rows: 1
3+
:widths: 20 20 80
4+
5+
* - Name
6+
- Type
7+
- Description
8+
9+
* - batchSize
10+
- integer
11+
- Specifies the batch size for the cursor, which will apply to both the
12+
initial ``aggregate`` command and any subsequent ``getMore`` commands.
13+
This determines the maximum number of change events to return in each
14+
response from the server.
15+
16+
.. note::
17+
18+
Irrespective of the ``batchSize`` option, the initial ``aggregate``
19+
command response for a change stream generally does not include any
20+
documents unless another option is used to configure its starting
21+
point (e.g. ``startAfter``).
22+
23+
* - collation
24+
- array|object
25+
- .. include:: /includes/option-collation.rst
26+
27+
* - comment
28+
- mixed
29+
- .. include:: /includes/option-comment.rst
30+
31+
The comment can be any valid BSON type for server versions 4.4 and above.
32+
Earlier server versions only support string values.
33+
34+
.. versionadded:: 1.13
35+
36+
* - fullDocument
37+
- string
38+
- Determines how the ``fullDocument`` response field will be populated for
39+
update operations.
40+
41+
By default, change streams only return the delta of fields (via an
42+
``updateDescription`` field) for update operations and ``fullDocument``
43+
is omitted. Insert and replace operations always include the
44+
``fullDocument`` field. Delete operations omit the field as the document
45+
no longer exists.
46+
47+
Specify "updateLookup" to return the current majority-committed version
48+
of the updated document.
49+
50+
MongoDB 6.0+ allows returning the post-image of the modified document if
51+
the collection has ``changeStreamPreAndPostImages`` enabled. Specify
52+
"whenAvailable" to return the post-image if available or a null value if
53+
not. Specify "required" to return the post-image if available or raise an
54+
error if not.
55+
56+
The following values are supported:
57+
58+
- ``MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP``
59+
- ``MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE``
60+
- ``MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED``
61+
62+
.. note::
63+
64+
This is an option of the ``$changeStream`` pipeline stage.
65+
66+
* - fullDocumentBeforeChange
67+
- string
68+
- Determines how the ``fullDocumentBeforeChange`` response field will be
69+
populated. By default, the field is omitted.
70+
71+
MongoDB 6.0+ allows returning the pre-image of the modified document if
72+
the collection has ``changeStreamPreAndPostImages`` enabled. Specify
73+
"whenAvailable" to return the pre-image if available or a null value if
74+
not. Specify "required" to return the pre-image if available or raise an
75+
error if not.
76+
77+
The following values are supported:
78+
79+
- ``MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE``
80+
- ``MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED``
81+
82+
.. note::
83+
84+
This is an option of the ``$changeStream`` pipeline stage.
85+
86+
.. versionadded: 1.13
87+
88+
* - maxAwaitTimeMS
89+
- integer
90+
- Positive integer denoting the time limit in milliseconds for the server
91+
to block a getMore operation if no data is available.
92+
93+
* - readConcern
94+
- :php:`MongoDB\\Driver\\ReadConcern <class.mongodb-driver-readconcern>`
95+
- .. include:: /includes/option-readConcern.rst
96+
97+
* - readPreference
98+
- :php:`MongoDB\\Driver\\ReadPreference <class.mongodb-driver-readpreference>`
99+
- .. include:: /includes/option-readPreference.rst
100+
101+
This is used for both the initial change stream aggregation and for
102+
server selection during an automatic resume.
103+
104+
* - resumeAfter
105+
- array|object
106+
- Specifies the logical starting point for the new change stream. The
107+
``_id`` field in documents returned by the change stream may be used
108+
here.
109+
110+
Using this option in conjunction with ``startAfter`` and/or
111+
``startAtOperationTime`` will result in a server error. The options are
112+
mutually exclusive.
113+
114+
.. note::
115+
116+
This is an option of the ``$changeStream`` pipeline stage.
117+
118+
* - session
119+
- :php:`MongoDB\\Driver\\Session <class.mongodb-driver-session>`
120+
- .. include:: /includes/option-session.rst
121+
122+
* - showExpandedEvents
123+
- boolean
124+
- If true, instructs the server to include additional DDL events in the
125+
change stream. The additional events that may be included are:
126+
127+
- ``createIndexes``
128+
- ``dropIndexes``
129+
- ``modify``
130+
- ``create``
131+
- ``shardCollection``
132+
- ``reshardCollection`` (server 6.1+)
133+
- ``refineCollectionShardKey`` (server 6.1+)
134+
135+
This is not supported for server versions prior to 6.0 and will result in
136+
an exception at execution time if used.
137+
138+
.. note::
139+
140+
This is an option of the ``$changeStream`` pipeline stage.
141+
142+
.. versionadded:: 1.13
143+
144+
* - startAfter
145+
- array|object
146+
- Specifies the logical starting point for the new change stream. The
147+
``_id`` field in documents returned by the change stream may be used
148+
here. Unlike ``resumeAfter``, this option can be used with a resume token
149+
from an "invalidate" event.
150+
151+
Using this option in conjunction with ``resumeAfter`` and/or
152+
``startAtOperationTime`` will result in a server error. The options are
153+
mutually exclusive.
154+
155+
This is not supported for server versions prior to 4.2 and will result in
156+
an exception at execution time if used.
157+
158+
.. note::
159+
160+
This is an option of the ``$changeStream`` pipeline stage.
161+
162+
.. versionadded: 1.5
163+
164+
* - startAtOperationTime
165+
- :php:`MongoDB\\BSON\\TimestampInterface <class.mongodb-bson-timestampinterface>`
166+
- If specified, the change stream will only provide changes that occurred
167+
at or after the specified timestamp. Command responses from a MongoDB
168+
4.0+ server include an ``operationTime`` that can be used here. By
169+
default, the ``operationTime`` returned by the initial ``aggregate``
170+
command will be used if available.
171+
172+
Using this option in conjunction with ``resumeAfter`` and/or
173+
``startAfter`` will result in a server error. The options are mutually
174+
exclusive.
175+
176+
This is not supported for server versions prior to 4.0 and will result in
177+
an exception at execution time if used.
178+
179+
.. note::
180+
181+
This is an option of the ``$changeStream`` pipeline stage.
182+
183+
* - typeMap
184+
- array
185+
- .. include:: /includes/option-typeMap.rst

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

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,11 @@ Definition
2424

2525
function addSubscriber(MongoDB\Driver\Monitoring\Subscriber $subscriber): void
2626

27-
This method has the following parameters:
28-
29-
.. include:: /includes/apiargs/MongoDBClient-method-addSubscriber-param.rst
30-
31-
.. note::
27+
Parameters
28+
----------
3229

33-
If ``$subscriber`` is already registered with this Client, this function
34-
is a no-op. If ``$subscriber`` is also registered globally, it will still
35-
only be notified once of each event for this Client.
30+
``$subscriber`` : :php:`MongoDB\\Driver\\Monitoring\\Subscriber <class.mongodb-driver-monitoring-subscriber>`
31+
A monitoring event subscriber to register with this Client.
3632

3733
Errors/Exceptions
3834
-----------------
@@ -44,6 +40,13 @@ if subscriber is a :php:`MongoDB\\Driver\\Monitoring\\LogSubscriber <class.mongo
4440
since loggers can only be registered globally with
4541
:php:`MongoDB\\Driver\\Monitoring\\addSubscriber <function.mongodb.driver.monitoring.addsubscriber>`.
4642

43+
Behavior
44+
--------
45+
46+
If ``$subscriber`` is already registered with this Client, this function is a
47+
no-op. If ``$subscriber`` is also registered globally, it will still only be
48+
notified once of each event for this Client.
49+
4750
Example
4851
-------
4952

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

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,18 @@ Definition
2222

2323
function createClientEncryption(array $options): MongoDB\Driver\ClientEncryption
2424

25-
This method has the following parameters:
25+
Parameters
26+
----------
2627

27-
.. include:: /includes/apiargs/MongoDBClient-method-createClientEncryption-param.rst
28+
``$options`` : array
29+
An array specifying the desired options. Refer to the
30+
:php:`MongoDB\\Driver\\Manager::createClientEncryption() <manual/en/mongodb-driver-manager.createclientencryption.php>`
31+
extension documentation for a list of supported options.
2832

29-
The ``$options`` parameter supports all options documented in the
30-
:php:`extension manual <manual/en/mongodb-driver-manager.createclientencryption.php>`.
31-
For the ``keyVaultClient`` option, an instance of :phpclass:`MongoDB\\Client`
32-
is automatically unwrapped and the :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>`
33-
instance is passed to the extension.
33+
If a :phpclass:`MongoDB\\Client` is provided for the ``keyVaultClient``
34+
option, it will be unwrapped into a
35+
:php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>` for the
36+
extension.
3437

3538
Return Values
3639
-------------

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

Lines changed: 40 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,49 @@ Definition
2121

2222
function dropDatabase(string $databaseName, array $options = []): array|object
2323

24-
This method has the following parameters:
24+
Parameters
25+
----------
26+
27+
``$databaseName`` : string
28+
The name of the database to drop.
29+
30+
``$options`` : array
31+
An array specifying the desired options.
32+
33+
.. |parent| replace:: client
34+
35+
.. list-table::
36+
:header-rows: 1
37+
:widths: 20 20 80
38+
39+
* - Name
40+
- Type
41+
- Description
42+
43+
* - comment
44+
- mixed
45+
- .. include:: /includes/option-comment.rst
46+
47+
This is not supported for server versions prior to 4.4 and will result
48+
in an exception at execution time if used.
49+
50+
.. versionadded:: 1.13
51+
52+
* - session
53+
- :php:`MongoDB\\Driver\\Session <class.mongodb-driver-session>`
54+
- .. include:: /includes/option-session.rst
55+
56+
.. versionadded:: 1.3
2557

26-
.. include:: /includes/apiargs/MongoDBClient-method-dropDatabase-param.rst
58+
* - typeMap
59+
- array
60+
- .. include:: /includes/option-typeMap.rst
2761

28-
The ``$options`` parameter supports the following options:
62+
This will be used for the returned command result document.
2963

30-
.. include:: /includes/apiargs/MongoDBClient-method-dropDatabase-option.rst
64+
* - writeConcern
65+
- :php:`MongoDB\\Driver\\WriteConcern <class.mongodb-driver-writeconcern>`
66+
- .. include:: /includes/option-writeConcern.rst
3167

3268
Return Values
3369
-------------

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

Lines changed: 48 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,57 @@ Definition
2323

2424
function listDatabaseNames(array $options = []): Iterator
2525

26-
This method has the following parameters:
26+
Parameters
27+
----------
28+
29+
``$options`` : array
30+
An array specifying the desired options.
31+
32+
.. list-table::
33+
:header-rows: 1
34+
:widths: 20 20 80
35+
36+
* - Name
37+
- Type
38+
- Description
39+
40+
* - authorizedDatabases
41+
- boolean
42+
- A flag that determines which databases are returned based on the user
43+
privileges when access control is enabled. For more information, see the
44+
`listDatabases command documentation <https://mongodb.com/docs/manual/reference/command/listDatabases/>`_.
45+
46+
For servers < 4.0.5, this option is ignored.
47+
48+
.. versionadded:: 1.7
49+
50+
* - comment
51+
- mixed
52+
- .. include:: /includes/option-comment.rst
53+
54+
This is not supported for server versions prior to 4.4 and will result
55+
in an exception at execution time if used.
56+
57+
.. versionadded:: 1.13
58+
59+
* - filter
60+
- array|object
61+
- A query expression to filter the list of databases.
62+
63+
You can specify a query expression for database fields (e.g. ``name``,
64+
``sizeOnDisk``, ``empty``).
65+
66+
.. versionadded:: 1.3
2767

28-
.. include:: /includes/apiargs/MongoDBClient-method-listDatabases-param.rst
68+
* - maxTimeMS
69+
- integer
70+
- .. include:: /includes/option-maxTimeMS.rst
2971

30-
The ``$options`` parameter supports the following options:
72+
* - session
73+
- :php:`MongoDB\\Driver\\Session <class.mongodb-driver-session>`
74+
- .. include:: /includes/option-session.rst
3175

32-
.. include:: /includes/apiargs/MongoDBClient-method-listDatabases-option.rst
76+
.. versionadded:: 1.3
3377

3478
Return Values
3579
-------------

0 commit comments

Comments
 (0)