DOCSP-41962 - Stable API

snooty.toml

@@ -27,6 +27,7 @@ php-library = "MongoDB PHP Library"
 
 php-library = "MongoDB PHP Library"
 driver-short = "PHP library"
+extension-short = "PHP extension"
 mdb-server = "MongoDB Server"
-driver-short = "PHP library"
+stable-api = "Stable API"
 api = "https://www.mongodb.com/docs/php-library/current/reference"

source/connect/stable-api.txt

@@ -0,0 +1,119 @@
+.. _php-stable-api:
+
+==============
+{+stable-api+}
+==============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: compatible, backwards, upgrade
+
+.. note::
+
+   The {+stable-api+} feature requires {+mdb-server+} 5.0 or later.
+
+Overview
+--------
+
+In this guide, you can learn how to specify **{+stable-api+}** compatibility when 
+connecting to a MongoDB deployment.
+
+The {+stable-api+} feature forces the server to run operations with behaviors compatible 
+with the API version you specify. When you update either your library or server version, 
+the API version changes, which can change the way these operations behave.
+Using the {+stable-api+} ensures consistent responses from the server and 
+provides long-term API stability for your application.
+
+The following sections describe how you can enable and customize {+stable-api+} for
+your MongoDB client. For more information about the {+stable-api+}, including a list of 
+the commands it supports, see :manual:`Stable API </reference/stable-api/>` in the
+{+mdb-server+} manual.
+
+Enable the {+stable-api+}
+-------------------------
+
+To enable the {+stable-api+}, perform the following steps:
+
+1. Construct a ``MongoDB\Driver\ServerApi`` object and pass the {+stable-api+}
+   version you want to use. Currently, the library supports only version 1.
+#. Construct a ``MongoDB\Client`` object. For the ``driverOptions`` parameter, pass an
+   array that contains the ``serverApi`` connection option. Set this option to the
+   ``MongoDB\Driver\ServerApi`` object you created in the previous step.
+
+The following code example shows how to specify {+stable-api+} version 1:
+
+.. literalinclude:: /includes/connect/stable-api.php
+   :language: php
+   :copyable: true
+   :start-after: // start-specify-v1
+   :end-before: // end-specify-v1
+   :emphasize-lines: 3-4
+
+.. note::
+
+   After you create a ``MongoDB\Client`` instance with
+   a specified API version, all commands you run with the client use the specified
+   version. If you need to run commands using more than one version of the 
+   {+stable-api+}, create a new ``MongoDB\Client`` instance.
+
+.. _stable-api-options:
+
+Configure the {+stable-api+}
+------------------------
+
+The ``MongoDB\Driver\ServerApi`` constructor also accepts the following optional parameters.
+You can use these parameters to customize the behavior of the {+stable-api+}.
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 25,75
+
+   * - Parameter
+     - Description
+
+   * - strict
+     - | **Optional**. When ``true``, if you call a command that isn't part of 
+         the declared API version, the server raises an exception.
+       |
+       | Default: ``null``. If this parameter is null, the server applies its default
+         value of ``false``. 
+
+   * -  deprecationErrors
+     - | **Optional**. When ``true``, if you call a command that is deprecated in the 
+         declared API version, the server raises an exception.
+       |
+       | Default: ``null``. If this parameter is null, the server applies its default
+         value of ``false``. 
+
+The following code example shows how you can use these parameters when constructing a 
+``MongoDB\Driver\ServerApi`` object:
+
+.. literalinclude:: /includes/connect/stable-api.php
+      :language: php
+      :copyable: true
+      :start-after: // start-stable-api-options
+      :end-before: // end-stable-api-options
+      :emphasize-lines: 3-4
+
+API Documentation
+-----------------
+
+For more information about the ``MongoDB\Client`` class, see the following {+driver-short+}
+API documentation:
+
+- :phpclass:`MongoDB\Client`
+
+For more information about the ``MongoDB\Driver\ServerApi`` class, see the following
+{+extension-short+} API documentation:
+
+- `MongoDB\\Driver\\ServerApi <https://www.php.net/manual/en/class.mongodb-driver-serverapi.php>`__

source/connect/tls.txt

@@ -265,4 +265,4 @@ API Documentation
 To learn more about configuring TLS for the {+driver-short+},
 see the following API documentation:
 
-- :ref:`MongoDB\Client <php-mongodb-client>`
+- :phpclass:`MongoDB\Client`

source/includes/connect/stable-api.php

@@ -0,0 +1,13 @@
+// start-specify-v1
+$uri = "mongodb://<hostname>:<port>";
+
+$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1')];
+$client = new MongoDB\Client($uri, [], $driverOptions);
+// end-specify-v1
+
+// start-stable-api-options
+$uri = "mongodb://<hostname>:<port>";
+
+$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1', strict: true, deprecationErrors: true)];
+$client = new MongoDB\Client($uri, [], $driverOptions);
+// end-stable-api-options