DOCSP-41959 - Connection Options

snooty.toml

@@ -25,3 +25,9 @@ php-library = "MongoDB PHP Library"
 [constants]
 php-library = "MongoDB PHP Library"
 api = "https://www.mongodb.com/docs/php-library/current/reference"
+driver-short = "PHP library"
+extension-short = "PHP extension"
+string-data-type = "``string``"
+bool-data-type = "``bool``"
+int-data-type = "``int``"
+mdb-server = "MongoDB Server"

source/connect/connection-options.txt

@@ -0,0 +1,356 @@
+.. _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.
+Configuring the connection this way makes it easier to
+change settings at runtime and helps you catch errors during compilation.
+
+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 ``MongoDB\Client`` object and in the connection
+   URI, the value in the ``MongoDB\Client`` object 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. 
+
+Replica Set Options
+~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Connection Option
+     - Description
+
+   * - :manual:`directConnection </reference/connection-string/#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/#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/#mongodb-urioption-urioption.connecttimeoutms>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = [ 'connectTimeoutMS' => 20000 ];``
+       | **Connection URI Example**: ``connectTimeoutMS=20000``
+
+   * - :manual:`socketTimeoutMS </reference/connection-string/#mongodb-urioption-urioption.sockettimeoutms>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = [ 'socketTimeoutMS' => 400000 ];``
+       | **Connection URI Example**: ``socketTimeoutMS=400000``
+
+.. _php-compression-options:
+
+Compression Options
+```````````````````
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Connection Option
+     - Description
+
+   * - :manual:`compressors </reference/connection-string/#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/#mongodb-urioption-urioption.zlibcompressionlevel>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = [ 'zlibCompressionLevel' => 3 ];``
+       | **Connection URI Example**: ``zlibCompressionLevel=3``
+
+Connection Pool Options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Connection Option
+     - Description
+
+   * - :manual:`maxPoolSize </reference/connection-string/#mongodb-urioption-urioption.maxpoolsize>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: N/A
+       | **Connection URI Example**: ``maxPoolSize=75``
+
+   * - :manual:`waitQueueTimeoutMS </reference/connection-string/#mongodb-urioption-urioption.waitqueuetimeoutms>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: N/A
+       | **Connection URI Example**: ``waitQueueTimeoutMS=10000``
+
+Write Concern Options
+~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Connection Option
+     - Description
+
+   * - :manual:`w </reference/connection-string/#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/#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/#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/#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/#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/#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/#mongodb-urioption-urioption.readpreferencetags>`
+     - | **Data Type**: ``array``
+       | **MongoDB\\Client Example**:
+
+       .. code-block:: php
+
+          $uriOptions = [
+            'readPreferenceTags' => [
+              [ 'region' => 'east' ],
+              [ 'region' => 'west']
+            ]
+          ];``
+
+       **Connection URI Example**: ``readPreferenceTags=region:east,region:west``
+
+Authentication Options
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Connection Option
+     - Description
+
+   * - :manual:`authMechanism </reference/connection-string/#mongodb-urioption-urioption.authmechanism>`
+     - | **Data Type**: {+string-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = [ 'authMechanism' => 'MONGODB-X509' ];``
+       | **Connection URI Example**: ``authMechanism=MONGODB-X509``
+
+   * - :manual:`authMechanismProperties </reference/connection-string/#mongodb-urioption-urioption.authmechanismproperties>`
+     - | **Data Type**: {+string-data-type+}
+       | **MongoDB\\Client Example**:
+       | ``$uriOptions = [ 'authMechanismProperties' => 'AWS_SESSION_TOKEN:12345' ];``
+       | 
+       | **Connection URI Example**: ``authMechanismProperties=AWS_SESSION_TOKEN:12345``
+
+   * - :manual:`authSource </reference/connection-string/#mongodb-urioption-urioption.authsource>`
+     - | **Data Type**: {+string-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = [ 'authSource' => 'admin' ];``
+       | **Connection URI Example**: ``authSource=admin``
+
+Server Selection and Discovery Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 30 70
+
+   * - Connection Option
+     - Description
+
+   * - :manual:`localThresholdMS </reference/connection-string/#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/#mongodb-urioption-urioption.serverselectiontimeoutms>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = [ 'serverSelectionTimeoutMS' => 40000 ];``
+       | **Connection URI Example**: ``serverSelectionTimeoutMS=40000``
+
+   * - :manual:`serverSelectionTryOnce </reference/connection-string/#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/#mongodb-urioption-urioption.heartbeatfrequencyms>`
+     - | **Data Type**: {+int-data-type+}
+       | **MongoDB\\Client Example**: ``$uriOptions = [ 'heartbeatFrequencyMS' => 50000 ];``
+       | **Connection URI Example**: ``heartbeatFrequencyMS=50000``
+
+   * - :manual:`socketCheckIntervalMS </reference/connection-string/#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/#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/#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/#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/#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/#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,21 @@
+// 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
+$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,3 +1,5 @@
+.. _php-mongodbclient:
+
 =====================
 MongoDB\\Client Class
 =====================