From c4c504ce06c4852a3d60edf97ec441fc189bd56c Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 28 Aug 2024 12:21:24 -0500 Subject: [PATCH 1/9] first draft --- snooty.toml | 2 +- source/connect/stable-api.txt | 117 +++++++++++++++++++++++++ source/connect/tls.txt | 2 +- source/includes/connect/stable-api.php | 23 +++++ 4 files changed, 142 insertions(+), 2 deletions(-) create mode 100644 source/connect/stable-api.txt create mode 100644 source/includes/connect/stable-api.php diff --git a/snooty.toml b/snooty.toml index e30bbbc3..290d34bb 100644 --- a/snooty.toml +++ b/snooty.toml @@ -27,6 +27,6 @@ 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" api = "https://www.mongodb.com/docs/php-library/current/reference" diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt new file mode 100644 index 00000000..b6551d77 --- /dev/null +++ b/source/connect/stable-api.txt @@ -0,0 +1,117 @@ +.. _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 driver or server, +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 driver 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: 5-7 + +.. 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 following table describes the parameters of the ``MongoDB\Driver\ServerApi`` constructor. +You can use these parameters to customize the behavior of the {+stable-api+}. + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 25,75 + + * - Option Name + - Description + + * - strict + - | **Optional**. When ``true``, if you call a command that isn't part of + the declared API version, the library raises an exception. + | + | Default: ``false`` + + * - deprecationErrors + - | **Optional**. When ``true``, if you call a command that is deprecated in the + declared API version, the library raises an exception. + | + | Default: ``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: 5-7 + +API Documentation +----------------- + +For more information about the ``MongoDB\Client`` class, see the following {+driver-short+} +API documentation: + +- :ref:`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/connect/tls.txt b/source/connect/tls.txt index f5e6fe23..f92304de 100644 --- a/source/connect/tls.txt +++ b/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 ` \ No newline at end of file +- :ref:`MongoDB\Client ` \ 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..989e93db --- /dev/null +++ b/source/includes/connect/stable-api.php @@ -0,0 +1,23 @@ +// start-specify-v1 +:"; + +$client = new MongoDB\Client($uri, [], [ + 'serverApi' => new MongoDB\Driver\ServerApi('1') +]); + +?> +// end-specify-v1 + +// start-stable-api-options +:"; + +$client = new MongoDB\Client($uri, [], [ + 'serverApi' => new MongoDB\Driver\ServerApi('1', true, true) +]); + +?> +// end-stable-api-options From a1b332295daff05170e5c0ead4c221b62188db2e Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 28 Aug 2024 12:22:38 -0500 Subject: [PATCH 2/9] add source constant --- snooty.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/snooty.toml b/snooty.toml index 290d34bb..c3284b54 100644 --- a/snooty.toml +++ b/snooty.toml @@ -29,4 +29,5 @@ php-library = "MongoDB PHP Library" driver-short = "PHP library" extension-short = "PHP extension" mdb-server = "MongoDB Server" +stable-api = "Stable API" api = "https://www.mongodb.com/docs/php-library/current/reference" From fde84d8b4ca36330b6e5001235052c487f3d56b2 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 5 Sep 2024 13:56:28 -0500 Subject: [PATCH 3/9] feedback --- source/connect/stable-api.txt | 10 +++++----- source/includes/connect/stable-api.php | 12 ++++++------ 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt index b6551d77..071c22a5 100644 --- a/source/connect/stable-api.txt +++ b/source/connect/stable-api.txt @@ -28,7 +28,7 @@ In this guide, you can learn how to specify **{+stable-api+}** compatibility whe 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 driver or server, +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. @@ -44,7 +44,7 @@ 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 driver supports only version 1. + 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. @@ -56,7 +56,7 @@ The following code example shows how to specify {+stable-api+} version 1: :copyable: true :start-after: // start-specify-v1 :end-before: // end-specify-v1 - :emphasize-lines: 5-7 + :emphasize-lines: 5-7, 9 .. note:: @@ -78,7 +78,7 @@ You can use these parameters to customize the behavior of the {+stable-api+}. :stub-columns: 1 :widths: 25,75 - * - Option Name + * - Parameter - Description * - strict @@ -101,7 +101,7 @@ The following code example shows how you can use these parameters when construct :copyable: true :start-after: // start-stable-api-options :end-before: // end-stable-api-options - :emphasize-lines: 5-7 + :emphasize-lines: 5-7, 9 API Documentation ----------------- diff --git a/source/includes/connect/stable-api.php b/source/includes/connect/stable-api.php index 989e93db..7902b22d 100644 --- a/source/includes/connect/stable-api.php +++ b/source/includes/connect/stable-api.php @@ -3,11 +3,11 @@ $uri = "mongodb://:"; -$client = new MongoDB\Client($uri, [], [ +$driverOptions = [ 'serverApi' => new MongoDB\Driver\ServerApi('1') -]); +]; -?> +$client = new MongoDB\Client($uri, [], $driverOptions); // end-specify-v1 // start-stable-api-options @@ -15,9 +15,9 @@ $uri = "mongodb://:"; -$client = new MongoDB\Client($uri, [], [ +$driverOptions = [ 'serverApi' => new MongoDB\Driver\ServerApi('1', true, true) -]); +]; -?> +$client = new MongoDB\Client($uri, [], $driverOptions); // end-stable-api-options From 1101bde16a48b6c10622fe858400915d5cdc3926 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 11 Sep 2024 10:04:46 -0500 Subject: [PATCH 4/9] phpclass directive --- source/connect/tls.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/tls.txt b/source/connect/tls.txt index f92304de..52a0b8c9 100644 --- a/source/connect/tls.txt +++ b/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 ` \ No newline at end of file +- :phpclass:`MongoDB\Client` \ No newline at end of file From 03f667a95dc67d23a3a3cc6cf1a4d02488ecc79b Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 11 Sep 2024 10:28:18 -0500 Subject: [PATCH 5/9] autobuilder From dd323f707e90d071b06af86bb2cb1bb4f7509589 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 11 Sep 2024 12:14:06 -0500 Subject: [PATCH 6/9] feedback --- source/connect/stable-api.txt | 18 ++++++++++-------- source/includes/connect/stable-api.php | 12 ++---------- 2 files changed, 12 insertions(+), 18 deletions(-) diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt index 071c22a5..8acb5a06 100644 --- a/source/connect/stable-api.txt +++ b/source/connect/stable-api.txt @@ -56,7 +56,7 @@ The following code example shows how to specify {+stable-api+} version 1: :copyable: true :start-after: // start-specify-v1 :end-before: // end-specify-v1 - :emphasize-lines: 5-7, 9 + :emphasize-lines: 3,5 .. note:: @@ -70,7 +70,7 @@ The following code example shows how to specify {+stable-api+} version 1: Configure the {+stable-api+} ------------------------ -The following table describes the parameters of the ``MongoDB\Driver\ServerApi`` constructor. +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:: @@ -83,15 +83,17 @@ You can use these parameters to customize the behavior of the {+stable-api+}. * - strict - | **Optional**. When ``true``, if you call a command that isn't part of - the declared API version, the library raises an exception. + the declared API version, the server raises an exception. | - | Default: ``false`` + | 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 library raises an exception. + declared API version, the server raises an exception. | - | Default: ``false`` + | 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: @@ -101,7 +103,7 @@ The following code example shows how you can use these parameters when construct :copyable: true :start-after: // start-stable-api-options :end-before: // end-stable-api-options - :emphasize-lines: 5-7, 9 + :emphasize-lines: 3,5 API Documentation ----------------- @@ -109,7 +111,7 @@ API Documentation For more information about the ``MongoDB\Client`` class, see the following {+driver-short+} API documentation: -- :ref:`MongoDB\Client ` +- :phpclass:`MongoDB\Client` For more information about the ``MongoDB\Driver\ServerApi`` class, see the following {+extension-short+} API documentation: diff --git a/source/includes/connect/stable-api.php b/source/includes/connect/stable-api.php index 7902b22d..6c4cc578 100644 --- a/source/includes/connect/stable-api.php +++ b/source/includes/connect/stable-api.php @@ -1,23 +1,15 @@ // start-specify-v1 -:"; -$driverOptions = [ - 'serverApi' => new MongoDB\Driver\ServerApi('1') -]; +$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1')]; $client = new MongoDB\Client($uri, [], $driverOptions); // end-specify-v1 // start-stable-api-options -:"; -$driverOptions = [ - 'serverApi' => new MongoDB\Driver\ServerApi('1', true, true) -]; +$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1', strict: true, deprecationErrors: true)]; $client = new MongoDB\Client($uri, [], $driverOptions); // end-stable-api-options From 5c80f1011f063a29998f0b40889df66e4d6b1cf2 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 11 Sep 2024 12:29:07 -0500 Subject: [PATCH 7/9] formatting --- source/connect/stable-api.txt | 4 ++-- source/includes/connect/stable-api.php | 2 -- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt index 8acb5a06..f1097ce5 100644 --- a/source/connect/stable-api.txt +++ b/source/connect/stable-api.txt @@ -56,7 +56,7 @@ The following code example shows how to specify {+stable-api+} version 1: :copyable: true :start-after: // start-specify-v1 :end-before: // end-specify-v1 - :emphasize-lines: 3,5 + :emphasize-lines: 3-4 .. note:: @@ -103,7 +103,7 @@ The following code example shows how you can use these parameters when construct :copyable: true :start-after: // start-stable-api-options :end-before: // end-stable-api-options - :emphasize-lines: 3,5 + :emphasize-lines: 3-4 API Documentation ----------------- diff --git a/source/includes/connect/stable-api.php b/source/includes/connect/stable-api.php index 6c4cc578..7b3dd969 100644 --- a/source/includes/connect/stable-api.php +++ b/source/includes/connect/stable-api.php @@ -2,7 +2,6 @@ $uri = "mongodb://:"; $driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1')]; - $client = new MongoDB\Client($uri, [], $driverOptions); // end-specify-v1 @@ -10,6 +9,5 @@ $uri = "mongodb://:"; $driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1', strict: true, deprecationErrors: true)]; - $client = new MongoDB\Client($uri, [], $driverOptions); // end-stable-api-options From ef8dcb3c682b3fc214cdbffbd9569382de9f6595 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 24 Sep 2024 08:29:07 -0500 Subject: [PATCH 8/9] Apply suggestions from code review Co-authored-by: Jeremy Mikola --- source/connect/stable-api.txt | 2 +- source/includes/connect/stable-api.php | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt index f1097ce5..d65bae63 100644 --- a/source/connect/stable-api.txt +++ b/source/connect/stable-api.txt @@ -46,7 +46,7 @@ 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 + 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: diff --git a/source/includes/connect/stable-api.php b/source/includes/connect/stable-api.php index 7b3dd969..fa32e98d 100644 --- a/source/includes/connect/stable-api.php +++ b/source/includes/connect/stable-api.php @@ -2,6 +2,7 @@ $uri = "mongodb://:"; $driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1')]; + $client = new MongoDB\Client($uri, [], $driverOptions); // end-specify-v1 From 4338b1026f7b18327fd45b510343db8a38981cd6 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 24 Sep 2024 08:41:55 -0500 Subject: [PATCH 9/9] feedback --- source/includes/connect/stable-api.php | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/includes/connect/stable-api.php b/source/includes/connect/stable-api.php index fa32e98d..f84470c4 100644 --- a/source/includes/connect/stable-api.php +++ b/source/includes/connect/stable-api.php @@ -1,3 +1,5 @@ +:"; @@ -9,6 +11,8 @@ // start-stable-api-options $uri = "mongodb://:"; -$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1', strict: true, deprecationErrors: true)]; +$serverApi = new MongoDB\Driver\ServerApi('1', strict: true, deprecationErrors: true); +$driverOptions = ['serverApi' => $serverApi]; + $client = new MongoDB\Client($uri, [], $driverOptions); // end-stable-api-options