DOCSP-41959 - Connection Options (#112)

Co-authored-by: Nora Reidy <nora.reidy@mongodb.com>
Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

Author: 3 people

snooty.toml

@@ -29,10 +29,10 @@ toc_landing_pages = [
     "/indexes",
     "/security",
     "/data-formats",
-    "/upgrade"
+    "/upgrade",
 ]
 
-sharedinclude_root =  "https://raw.githubusercontent.com/10gen/docs-shared/main/"
+sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 
 [substitutions]
 php-library = "MongoDB PHP Library"
@@ -46,3 +46,6 @@ 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"
+string-data-type = "``string``"
+bool-data-type = "``bool``"
+int-data-type = "``int``"

source/connect.txt

@@ -24,10 +24,8 @@ Connect to MongoDB
 
    /connect/client
    /connect/connection-targets
-   /connect/tls
-
-.. TODO:
    /connect/connection-options
+   /connect/tls
    /connect/stable-api
 
 Overview

source/connect/connection-options.txt

@@ -0,0 +1,328 @@
+.. _php-connection-options:
+
+==========================
+Specify Connection Options
+==========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: connection string, URI, server, Atlas, settings, configure
+
+Overview
+--------
+
+This page describes the MongoDB connection and authentication options
+available in the {+driver-short+}.
+
+Set Connection Options
+----------------------
+
+You can configure your connection by specifying options in the connection URI or by
+passing them to the ``MongoDB\Client`` constructor.
+
+.. _php-connection-uri:
+
+Using the Connection URI
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you pass a connection URI to the ``MongoDB\Client`` constructor, you can include
+connection options in the URI as ``<name>=<value>`` pairs. In the following example,
+the connection URI sets the ``tls`` option to ``true`` and the
+``tlsCertificateKeyFile`` option to ``/path/to/file.pem``:
+
+.. literalinclude:: /includes/connect/connection-options.php
+   :language: php
+   :copyable: true
+   :start-after: // start-connection-uri
+   :end-before: // end-connection-uri
+   :emphasize-lines: 2,5
+
+.. _php-client-object:
+
+Using a MongoDB\\Client Object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can pass connection options to the ``MongoDB\Client`` constructor
+instead of including them in your connection URI.
+
+The following example shows how to use the ``$uriOptions`` parameter of the
+``MongoDB\Client`` constructor to set connection options:
+
+.. literalinclude:: /includes/connect/connection-options.php
+   :language: php
+   :copyable: true
+   :start-after: // start-client-options 
+   :end-before: // end-client-options
+   :emphasize-lines: 5-8, 11
+
+.. note::
+   
+   If you specify an option in both the ``$uriOptions`` parameter and in the connection
+   URI, the value in ``$uriOptions`` takes precedence.
+
+Connection URI Options
+----------------------
+
+The following sections describe the options that you can set for your connection to
+MongoDB. Each connection option links to its corresponding
+entry in the {+mdb-server+} manual.
+
+.. important:: Percent-Encoding
+
+   If the value of a connection option contains special characters, you must
+   :wikipedia:`percent-encode <Percent-encoding>` the value before including it
+   in the connection URI. You can use the ``rawurlencode()`` method to encode 
+   these values according to the URI syntax specified in RFC 3986.
+
+   Don't percent-encode connection options when including them in the
+   ``$uriOptions`` parameter.
+
+   To learn more, see the following resources:
+
+   - `RFC 3986 <http://www.faqs.org/rfcs/rfc3986.html>`__
+   - `rawurlencode <{+php-manual+}/rawurlencode>`__ in the PHP manual
+
+Replica Set Options
+~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Connection Option
+     - Description
+
+   * - :manual:`directConnection </reference/connection-string-options/#mongodb-urioption-urioption.directConnection>`
+     - | **Data Type**: {+bool-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['directConnection' => true];``
+       | **Connection URI Example**: ``directConnection=true``
+   
+   * - :manual:`replicaSet </reference/connection-string-options/#mongodb-urioption-urioption.replicaSet>`
+     - | **Data Type**: {+string-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['replicaSet' => 'replicaSetName'];``
+       | **Connection URI Example**: ``replicaSet=replicaSetName``
+   
+Connection Options
+~~~~~~~~~~~~~~~~~~
+
+TLS Options
+```````````
+To learn about the TLS options available in the {+driver-short+}, see the
+:ref:`TLS <php-tls>` page.
+
+Timeout Options
+```````````````
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Connection Option
+     - Description
+
+   * - :manual:`connectTimeoutMS </reference/connection-string-options/#mongodb-urioption-urioption.connecttimeoutms>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['connectTimeoutMS' => 2000];``
+       | **Connection URI Example**: ``connectTimeoutMS=2000``
+
+   * - :manual:`socketTimeoutMS </reference/connection-string-options/#mongodb-urioption-urioption.sockettimeoutms>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['socketTimeoutMS' => 20000];``
+       | **Connection URI Example**: ``socketTimeoutMS=20000``
+
+.. _php-compression-options:
+
+Compression Options
+```````````````````
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Connection Option
+     - Description
+
+   * - :manual:`compressors </reference/connection-string-options/#mongodb-urioption-urioption.compressors>`
+     - | **Data Type**: {+string-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['compressors' => 'snappy,zstd,zlib'];``
+       | **Connection URI Example**: ``compressors=snappy,zstd,zlib``
+
+   * - :manual:`zlibCompressionLevel </reference/connection-string-options/#mongodb-urioption-urioption.zlibcompressionlevel>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['zlibCompressionLevel' => 3];``
+       | **Connection URI Example**: ``zlibCompressionLevel=3``
+
+Write Concern Options
+~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Connection Option
+     - Description
+   
+   * - :manual:`w </reference/connection-string-options/#mongodb-urioption-urioption.w>` 
+     - | **Data Type**: {+string-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['w' => 'majority'];``
+       | **Connection URI Example**: ``w=majority``
+
+   * - :manual:`wTimeoutMS </reference/connection-string-options/#mongodb-urioption-urioption.wtimeoutms>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['wTimeoutMS' => 10000];``
+       | **Connection URI Example**: ``wTimeoutMS=10000``
+
+   * - :manual:`journal </reference/connection-string-options/#mongodb-urioption-urioption.journal>` 
+     - | **Data Type**: {+bool-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['journal' => true];``
+       | **Connection URI Example**: ``journal=true``
+
+Read Concern Options
+~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Connection Option
+     - Description
+   
+   * - :manual:`readConcernLevel </reference/connection-string-options/#mongodb-urioption-urioption.readconcernlevel>`
+     - | **Data Type**: {+string-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['readConcernLevel' => 'majority'];``
+       | **Connection URI Example**: ``readConcernLevel=majority``
+
+Read Preference Options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 22 78
+
+   * - Connection Option
+     - Description
+   
+   * - :manual:`readPreference </reference/connection-string-options/#mongodb-urioption-urioption.readpreference>`
+     - | **Data Type**: `MongoDB\\Driver\\ReadPreference <https://www.php.net/manual/en/class.mongodb-driver-readpreference.php>`__
+       | **MongoDB\\Client Example**: ``$uriOptions = ['readPreference' => 'secondaryPreferred'];``
+       | **Connection URI Example**: ``readPreference=secondaryPreferred``
+   
+   * - :manual:`maxStalenessSeconds </reference/connection-string-options/#mongodb-urioption-urioption.maxstalenessseconds>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['maxStalenessSeconds' => 30];``
+       | **Connection URI Example**: ``maxStalenessSeconds=30``
+
+   * - :manual:`readPreferenceTags </reference/connection-string-options/#mongodb-urioption-urioption.readpreferencetags>`
+     - | **Data Type**: ``array``
+       | **MongoDB\\Client Example**:
+       
+       .. code-block:: php
+
+          $uriOptions = [
+              'readPreferenceTags' => [
+                  ['dc' => 'ny', 'rack' => 'r1'],
+                  [],
+              ],
+          ];
+        
+       **Connection URI Example**: ``readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=``
+
+Authentication Options
+~~~~~~~~~~~~~~~~~~~~~~
+
+To learn about the authentication options available in the {+driver-short+}, see
+:ref:`Authentication Mechanisms. <php-auth>`
+
+Server Selection and Discovery Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 30 70
+
+   * - Connection Option
+     - Description
+   
+   * - :manual:`localThresholdMS </reference/connection-string-options/#mongodb-urioption-urioption.localthresholdms>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['localThresholdMS' => 20];``
+       | **Connection URI Example**: ``localThresholdMS=20``
+
+   * - :manual:`serverSelectionTimeoutMS </reference/connection-string-options/#mongodb-urioption-urioption.serverselectiontimeoutms>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['serverSelectionTimeoutMS' => 5000];``
+       | **Connection URI Example**: ``serverSelectionTimeoutMS=5000``
+
+   * - :manual:`serverSelectionTryOnce </reference/connection-string-options/#mongodb-urioption-urioption.serverselectiontryonce>`
+     - | **Data Type**: {+bool-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['serverSelectionTryOnce' => false];``
+       | **Connection URI Example**: ``serverSelectionTryOnce=false``
+
+   * - :manual:`heartbeatFrequencyMS </reference/connection-string-options/#mongodb-urioption-urioption.heartbeatfrequencyms>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['heartbeatFrequencyMS' => 30000];``
+       | **Connection URI Example**: ``heartbeatFrequencyMS=30000``
+
+   * - :manual:`socketCheckIntervalMS </reference/connection-string-options/#mongodb-urioption-urioption.socketcheckintervalms>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['socketCheckIntervalMS' => 4000];``
+       | **Connection URI Example**: ``socketCheckIntervalMS=4000``
+
+Miscellaneous Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Connection Option
+     - Description
+   
+   * - :manual:`appName </reference/connection-string-options/#mongodb-urioption-urioption.appname>`
+     - | **Data Type**: {+string-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['appName' => 'myApp'];``
+       | **Connection URI Example**: ``appName=myApp``
+
+   * - :manual:`retryReads </reference/connection-string-options/#mongodb-urioption-urioption.retryreads>`
+     - | **Data Type**: {+bool-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['retryReads' => false];``
+       | **Connection URI Example**: ``retryReads=false``
+
+   * - :manual:`retryWrites </reference/connection-string-options/#mongodb-urioption-urioption.retrywrites>`
+     - | **Data Type**: {+bool-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['retryWrites' => false];``
+       | **Connection URI Example**: ``retryWrites=false``
+   
+   * - :manual:`loadBalanced </reference/connection-string-options/#mongodb-urioption-urioption.loadbalanced>`
+     - | **Data Type**: {+bool-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['loadBalanced' => true];``
+       | **Connection URI Example**: ``loadBalanced=true``
+
+   * - :manual:`srvMaxHosts </reference/connection-string-options/#mongodb-urioption-urioption.srvmaxhosts>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = ['srvMaxHosts' => 5];``
+       | **Connection URI Example**: ``srvMaxHosts=5``
+
+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\ReadPreference`` class, see the following
+{+extension-short+} API documentation:
+
+- `MongoDB\\Driver\\ReadPreference <https://www.php.net/manual/en/class.mongodb-driver-readpreference.php>`__

source/includes/connect/connection-options.php

@@ -0,0 +1,22 @@
+// start-connection-uri
+// Replace the placeholders with your actual hostname, port, and path to the certificate key file
+$uri = "mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/file.pem";
+
+// Create a MongoDB client
+$client = new MongoDB\Client($uri);
+// end-connection-uri
+
+// start-client-options
+// Replace the placeholders with your actual hostname and port
+$uri = "mongodb://<hostname>:<port>/";
+
+// Set the connection options
+// Replace the placeholder with the actual path to the certificate key file
+$uriOptions = [
+    'tls' => true,
+    'tlsCertificateKeyFile' => '/path/to/file.pem'
+];
+
+// Create a MongoDB client with the URI and options
+$client = new Client($uri, $uriOptions);
+// end-client-options

source/reference/class/MongoDBClient.txt

@@ -1,5 +1,3 @@
-.. _php-api-mongodbclient:
-
 =====================
 MongoDB\\Client Class
 =====================