diff --git a/snooty.toml b/snooty.toml index 9cd0f222..051763b9 100644 --- a/snooty.toml +++ b/snooty.toml @@ -36,8 +36,10 @@ php-library = "MongoDB PHP Library" [constants] php-library = "MongoDB PHP Library" -library-short = "PHP library" -stable-api = "Stable API" +driver-short = "PHP library" +extension-short = "PHP extension" mdb-server = "MongoDB Server" +stable-api = "Stable API" +library-short = "PHP library" api = "https://www.mongodb.com/docs/php-library/current/reference" php-manual = "https://www.php.net/manual/en" diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt new file mode 100644 index 00000000..d65bae63 --- /dev/null +++ b/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 ` 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`` 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 `__ \ No newline at end of file diff --git a/source/includes/connect/stable-api.php b/source/includes/connect/stable-api.php new file mode 100644 index 00000000..f84470c4 --- /dev/null +++ b/source/includes/connect/stable-api.php @@ -0,0 +1,18 @@ +:"; + +$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1')]; + +$client = new MongoDB\Client($uri, [], $driverOptions); +// end-specify-v1 + +// start-stable-api-options +$uri = "mongodb://:"; + +$serverApi = new MongoDB\Driver\ServerApi('1', strict: true, deprecationErrors: true); +$driverOptions = ['serverApi' => $serverApi]; + +$client = new MongoDB\Client($uri, [], $driverOptions); +// end-stable-api-options