PHPLIB-621 Document Versioned API usage

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

@@ -1,4 +1,58 @@
 arg_name: option
+name: autoEncryption
+type: array
+description: |
+  Options to configure client-side field-level encryption in the driver. The
+  encryption options are documented in the :php:`extension documentation
+  <manual/en/mongodb-driver-manager.construct.php#mongodb-driver-manager.construct-driveroptions>`.
+  For the ``keyVaultClient`` option, you may pass a :phpclass:`MongoDB\\Client`
+  instance, which will be unwrapped to provide a :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>`
+  to the extension.
+  .. versionadded:: 1.6
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: driver
+type: array
+description: |
+  Additional driver metadata to be passed on to the server handshake. This is an
+  array containing ``name``, ``version``, and ``platform`` fields:
+
+  .. code-block:: php
+
+     [
+         'name' => 'my-driver',
+         'version' => '1.2.3-dev',
+         'platform' => 'some-platform',
+     ]
+
+  .. note::
+
+     This feature is primarily designed for custom drivers and ODMs, which may
+     want to identify themselves to the server for diagnostic purposes.
+     Applications should use the ``appName`` URI option instead of driver
+     metadata.
+
+  .. versionadded:: 1.7
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: serverApi
+type: :php:`MongoDB\\Driver\\ServerApi <class.mongodb-driver-serverapi>`
+description: |
+  Used to declare an API version on the client. See the
+  :manual:`Versioned API tutorial </tutorial/versioned-api>` for usage.
+
+  .. versionadded:: 1.9
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
 name: typeMap
 type: array
 description: |
@@ -131,46 +185,4 @@ description: |
 interface: phpmethod
 operation: ~
 optional: true
----
-arg_name: option
-name: autoEncryption
-type: array
-description: |
-  Options to configure client-side field-level encryption in the driver. The
-  encryption options are documented in the :php:`extension documentation
-  <manual/en/mongodb-driver-manager.construct.php#mongodb-driver-manager.construct-driveroptions>`.
-  For the ``keyVaultClient`` option, you may pass a :phpclass:`MongoDB\\Client`
-  instance, which will be unwrapped to provide a :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>`
-  to the extension.
-  .. versionadded:: 1.6
-interface: phpmethod
-operation: ~
-optional: true
----
-arg_name: option
-name: driver
-type: array
-description: |
-  Additional driver metadata to be passed on to the server handshake. This is an
-  array containing ``name``, ``version``, and ``platform`` fields:
-
-  .. code-block:: php
-
-     [
-         'name' => 'my-driver',
-         'version' => '1.2.3-dev',
-         'platform' => 'some-platform',
-     ]
-
-  .. note::
-
-     This feature is primarily designed for custom drivers and ODMs, which may
-     want to identify themselves to the server for diagnostic purposes.
-     Applications should use the ``appName`` URI option instead of driver
-     metadata.
-
-  .. versionadded:: 1.7
-interface: phpmethod
-operation: ~
-optional: true
 ...

docs/tutorial.txt

@@ -15,3 +15,4 @@ Tutorials
    /tutorial/indexes
    /tutorial/tailable-cursor
    /tutorial/example-data
+   /tutorial/versioned-api

docs/tutorial/versioned-api.txt

@@ -0,0 +1,94 @@
+=============
+Versioned API
+=============
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Declaring an API version
+------------------------
+
+To declare an API version, pass a ``serverApi`` driver option when creating your
+client. The value is a
+:php:`MongoDB\\Driver\\ServerApi <class.mongodb-driver-serverapi>` instance that
+contains API version information. This feature is introduced in MongoDB 5.0,
+which will initially support only API version "1". Additional versions may be
+introduced in future versions of the server.
+
+.. code-block:: php
+
+   <?php
+
+   use MongoDB\Client;
+   use MongoDB\Driver\ServerApi;
+
+   $serverApi = new ServerApi(ServerApi::V1);
+   $client = new Client('mongodb://127.0.0.1', [], ['serverApi' => $serverApi]);
+
+   // Command includes the declared API version
+   $client->database->collection->find([]);
+
+.. note::
+
+   Only declare an API version when connecting to a deployment that has no
+   pre-5.0 members. Older servers will error when encountering commands with a
+   declared API version.
+
+Strict API
+----------
+
+By default, declaring an API version guarantees behavior for commands that are
+part of the versioned API, but does not forbid using commands that are not part
+of the API version. To only allow commands and options that are part of the
+versioned API, specify the ``strict`` option when creating the
+specify the ``strict`` option when creating the
+:php:`MongoDB\\Driver\\ServerApi <class.mongodb-driver-serverapi>` instance:
+
+.. code-block:: php
+
+   <?php
+
+   use MongoDB\Client;
+   use MongoDB\Driver\ServerApi;
+
+   $serverApi = new ServerApi(ServerApi::V1, true);
+   $client = new Client('mongodb://127.0.0.1', [], ['serverApi' => $serverApi]);
+
+   // Will fail as the tailable option is not supported in versioned API
+   $client->database->collection->find([], ['tailable' => true]);
+
+Fail on Deprecated Commands
+---------------------------
+
+The optional ``deprecationErrors`` option causes MongoDB to fail all commands
+or behaviors that have been deprecated in the API version. This can be used in
+testing to ensure a smooth transition to a future API version.
+
+.. code-block:: php
+
+   <?php
+
+   use MongoDB\Client;
+   use MongoDB\Driver\ServerApi;
+
+   $serverApi = new ServerApi(ServerApi::V1, null, true);
+   $client = new Client('mongodb://127.0.0.1', [], ['serverApi' => $serverApi]);
+
+.. note::
+
+   At the time of this writing, no part of API version "1" has been deprecated.
+
+Usage with the command helper
+-----------------------------
+
+When using the :phpmethod:`MongoDB\\Database::command()` method to run arbitrary
+commands, the API version declared to the client is automatically appended to
+the command document. Setting any of the ``apiVersion``, ``apiStrict``, or
+``apiDeprecationErrors`` command options in the command document and calling
+:phpmethod:`MongoDB\\Database::command()` from a client with a declared API
+version is not supported and will lead to undefined behavior.