Skip to content

Commit 21e7ecd

Browse files
alcaeusjmikola
alcaeus
and
jmikola
authored
PHPLIB-621 Document Versioned API usage (#815)
* Move non-deprecated driver options to the top * Document versioned API usage * Document serverApi driver option * Apply suggestions from code review Co-authored-by: Jeremy Mikola <[email protected]> Co-authored-by: Jeremy Mikola <[email protected]>
1 parent d1b18dd commit 21e7ecd

File tree

3 files changed

+149
-42
lines changed

3 files changed

+149
-42
lines changed

‎docs/includes/apiargs-MongoDBClient-method-construct-driverOptions.yaml

Lines changed: 54 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,58 @@
11
arg_name: option
2+
name: autoEncryption
3+
type: array
4+
description: |
5+
Options to configure client-side field-level encryption in the driver. The
6+
encryption options are documented in the :php:`extension documentation
7+
<manual/en/mongodb-driver-manager.construct.php#mongodb-driver-manager.construct-driveroptions>`.
8+
For the ``keyVaultClient`` option, you may pass a :phpclass:`MongoDB\\Client`
9+
instance, which will be unwrapped to provide a :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>`
10+
to the extension.
11+
.. versionadded:: 1.6
12+
interface: phpmethod
13+
operation: ~
14+
optional: true
15+
---
16+
arg_name: option
17+
name: driver
18+
type: array
19+
description: |
20+
Additional driver metadata to be passed on to the server handshake. This is an
21+
array containing ``name``, ``version``, and ``platform`` fields:
22+
23+
.. code-block:: php
24+
25+
[
26+
'name' => 'my-driver',
27+
'version' => '1.2.3-dev',
28+
'platform' => 'some-platform',
29+
]
30+
31+
.. note::
32+
33+
This feature is primarily designed for custom drivers and ODMs, which may
34+
want to identify themselves to the server for diagnostic purposes.
35+
Applications should use the ``appName`` URI option instead of driver
36+
metadata.
37+
38+
.. versionadded:: 1.7
39+
interface: phpmethod
40+
operation: ~
41+
optional: true
42+
---
43+
arg_name: option
44+
name: serverApi
45+
type: :php:`MongoDB\\Driver\\ServerApi <class.mongodb-driver-serverapi>`
46+
description: |
47+
Used to declare an API version on the client. See the
48+
:manual:`Versioned API tutorial </tutorial/versioned-api>` for usage.
49+
50+
.. versionadded:: 1.9
51+
interface: phpmethod
52+
operation: ~
53+
optional: true
54+
---
55+
arg_name: option
256
name: typeMap
357
type: array
458
description: |
@@ -131,46 +185,4 @@ description: |
131185
interface: phpmethod
132186
operation: ~
133187
optional: true
134-
---
135-
arg_name: option
136-
name: autoEncryption
137-
type: array
138-
description: |
139-
Options to configure client-side field-level encryption in the driver. The
140-
encryption options are documented in the :php:`extension documentation
141-
<manual/en/mongodb-driver-manager.construct.php#mongodb-driver-manager.construct-driveroptions>`.
142-
For the ``keyVaultClient`` option, you may pass a :phpclass:`MongoDB\\Client`
143-
instance, which will be unwrapped to provide a :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>`
144-
to the extension.
145-
.. versionadded:: 1.6
146-
interface: phpmethod
147-
operation: ~
148-
optional: true
149-
---
150-
arg_name: option
151-
name: driver
152-
type: array
153-
description: |
154-
Additional driver metadata to be passed on to the server handshake. This is an
155-
array containing ``name``, ``version``, and ``platform`` fields:
156-
157-
.. code-block:: php
158-
159-
[
160-
'name' => 'my-driver',
161-
'version' => '1.2.3-dev',
162-
'platform' => 'some-platform',
163-
]
164-
165-
.. note::
166-
167-
This feature is primarily designed for custom drivers and ODMs, which may
168-
want to identify themselves to the server for diagnostic purposes.
169-
Applications should use the ``appName`` URI option instead of driver
170-
metadata.
171-
172-
.. versionadded:: 1.7
173-
interface: phpmethod
174-
operation: ~
175-
optional: true
176188
...

‎docs/tutorial.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,4 @@ Tutorials
1515
/tutorial/indexes
1616
/tutorial/tailable-cursor
1717
/tutorial/example-data
18+
/tutorial/versioned-api

‎docs/tutorial/versioned-api.txt

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
=============
2+
Versioned API
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+
Declaring an API version
14+
------------------------
15+
16+
To declare an API version, pass a ``serverApi`` driver option when creating your
17+
client. The value is a
18+
:php:`MongoDB\\Driver\\ServerApi <class.mongodb-driver-serverapi>` instance that
19+
contains API version information. This feature is introduced in MongoDB 5.0,
20+
which will initially support only API version "1". Additional versions may be
21+
introduced in future versions of the server.
22+
23+
.. code-block:: php
24+
25+
<?php
26+
27+
use MongoDB\Client;
28+
use MongoDB\Driver\ServerApi;
29+
30+
$serverApi = new ServerApi(ServerApi::V1);
31+
$client = new Client('mongodb://127.0.0.1', [], ['serverApi' => $serverApi]);
32+
33+
// Command includes the declared API version
34+
$client->database->collection->find([]);
35+
36+
.. note::
37+
38+
Only declare an API version when connecting to a deployment that has no
39+
pre-5.0 members. Older servers will error when encountering commands with a
40+
declared API version.
41+
42+
Strict API
43+
----------
44+
45+
By default, declaring an API version guarantees behavior for commands that are
46+
part of the versioned API, but does not forbid using commands that are not part
47+
of the API version. To only allow commands and options that are part of the
48+
versioned API, specify the ``strict`` option when creating the
49+
specify the ``strict`` option when creating the
50+
:php:`MongoDB\\Driver\\ServerApi <class.mongodb-driver-serverapi>` instance:
51+
52+
.. code-block:: php
53+
54+
<?php
55+
56+
use MongoDB\Client;
57+
use MongoDB\Driver\ServerApi;
58+
59+
$serverApi = new ServerApi(ServerApi::V1, true);
60+
$client = new Client('mongodb://127.0.0.1', [], ['serverApi' => $serverApi]);
61+
62+
// Will fail as the tailable option is not supported in versioned API
63+
$client->database->collection->find([], ['tailable' => true]);
64+
65+
Fail on Deprecated Commands
66+
---------------------------
67+
68+
The optional ``deprecationErrors`` option causes MongoDB to fail all commands
69+
or behaviors that have been deprecated in the API version. This can be used in
70+
testing to ensure a smooth transition to a future API version.
71+
72+
.. code-block:: php
73+
74+
<?php
75+
76+
use MongoDB\Client;
77+
use MongoDB\Driver\ServerApi;
78+
79+
$serverApi = new ServerApi(ServerApi::V1, null, true);
80+
$client = new Client('mongodb://127.0.0.1', [], ['serverApi' => $serverApi]);
81+
82+
.. note::
83+
84+
At the time of this writing, no part of API version "1" has been deprecated.
85+
86+
Usage with the command helper
87+
-----------------------------
88+
89+
When using the :phpmethod:`MongoDB\\Database::command()` method to run arbitrary
90+
commands, the API version declared to the client is automatically appended to
91+
the command document. Setting any of the ``apiVersion``, ``apiStrict``, or
92+
``apiDeprecationErrors`` command options in the command document and calling
93+
:phpmethod:`MongoDB\\Database::command()` from a client with a declared API
94+
version is not supported and will lead to undefined behavior.

0 commit comments

Comments
 (0)