DOCSP-35941 connection options (#2892)

* DOCSP-35941: Connection Options docs

Author: Chris Cho

docs/fundamentals.txt

@@ -22,8 +22,7 @@ Fundamentals
 
 Learn how to use the {+odm-long+} to perform the following tasks:
 
-- :ref:`Configure Your MongoDB Connection <laravel-fundamentals-connection>`
-- :ref:`Databases and Collections <laravel-db-coll>`
-- :ref:`Read Operations <laravel-fundamentals-read-ops>`
-- :ref:`Write Operations <laravel-fundamentals-write-ops>`
-
+- :ref:`laravel-fundamentals-connection`
+- :ref:`laravel-db-coll`
+- :ref:`laravel-fundamentals-read-ops`
+- :ref:`laravel-fundamentals-write-ops`

docs/fundamentals/connection.txt

@@ -7,6 +7,7 @@ Connections
 .. toctree::
 
    /fundamentals/connection/connect-to-mongodb
+   /fundamentals/connection/connection-options
 
 .. contents:: On this page
    :local:
@@ -17,9 +18,8 @@ Connections
 Overview
 --------
 
-Learn how to set up a connection from your Laravel application to a MongoDB
-deployment and specify the connection behavior by using {+odm-short+} in the
-following sections:
+Learn how to use {+odm-short+} to set up a connection to a MongoDB deployment
+and specify connection behavior in the following sections:
 
 - :ref:`laravel-connect-to-mongodb`
-
+- :ref:`laravel-fundamentals-connection-options`

docs/fundamentals/connection/connection-options.txt

@@ -0,0 +1,349 @@
+.. _laravel-fundamentals-connection-options:
+
+==================
+Connection Options
+==================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, data source name, dsn, authentication, configuration, options, driverOptions
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn about connection, authentication, and driver
+options and how to specify them in your Laravel application's database
+connection configuration. Connection options are passed to the {+php-library+},
+which manages your database connections.
+
+To learn more about the {+php-library+}, see the
+`{+php-library+} documentation <https://www.mongodb.com/docs/php-library/current/>`__.
+
+This guide covers the following topics:
+
+- :ref:`laravel-connection-auth-options`
+- :ref:`laravel-driver-options`
+
+.. _laravel-connection-auth-options:
+
+Connection and Authentication Options
+-------------------------------------
+
+Learn how to add common connection and authentication options to your
+configuration file in the following sections:
+
+- :ref:`laravel-connection-auth-example`
+- :ref:`laravel-connection-auth-descriptions`
+
+.. _laravel-connection-auth-example:
+
+Add Connection and Authentication Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can specify connection or authentication options in your Laravel web
+application's ``config/database.php`` configuration file by using one of the
+following methods:
+
+- Add the setting and value as an array item in the ``options`` array item.
+- Append the setting and value as a query string parameter on the connection
+  string specified in the ``dsn`` array item.
+
+To specify an option in the ``options`` array, add its name and value as an
+array item, as shown in the following example:
+
+.. code-block:: php
+   :emphasize-lines: 6-10
+
+   'connections' => [
+       'mongodb' => [
+           'dsn' => 'mongodb+srv://mongodb0.example.com/',
+           'driver' => 'mongodb',
+           'database' => 'sample_mflix',
+           'options' => [
+               'appName' => 'myLaravelApp',
+               'compressors' => 'zlib',
+               'zlibCompressionLevel' => 7,
+           ],
+       ],
+   ],
+
+To specify options as parameters in the connection string, use the following
+query string syntax formatting:
+
+- Add the question mark character, ``?``, to separate the host information
+  from the parameters.
+- Add the options by formatting them as ``<option>=<value>``.
+- Insert the ampersand character, ``&``, between each option and value pair
+  to separate them.
+
+The following setting example shows the connection string parameter syntax:
+
+.. code-block:: php
+
+   'dsn' => 'mongodb+srv://mongodb0.example.com/?appName=myLaravelApp&compressors=zlib',
+
+.. _laravel-connection-auth-descriptions:
+
+Option Descriptions
+~~~~~~~~~~~~~~~~~~~
+
+The following table describes a list of connection and authentication options
+and their default values:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 12 12 46
+
+   * - Option Name
+     - Accepted Values
+     - Default Value
+     - Description
+
+   * - **appName**
+     - String
+     - None
+     - | Specifies the application name that the {+php-library+} sends the
+         MongoDB deployment as part of the handshake.
+       | Specifying ``appName`` can help you identify activities related
+         to that application in the server logs.
+
+   * - **authMechanism**
+     - String
+     - None
+     - Specifies which authentication mechanism to use. If you do not
+       specify this option, the driver uses the default authentication
+       mechanism. To learn more, see :manual:`Authentication </core/authentication/>`
+       in the {+server-docs-name+}.
+
+   * - **authMechanismProperties**
+     - String
+     - None
+     - Specifies more properties related to the authentication mechanism set in
+       the ``authMechanism`` option.
+
+   * - **authSource**
+     - String
+     - See description
+     - | Specifies the database used to authenticate.
+       | This option defaults to ``admin`` for SCRAM-based authentication
+         mechanisms, ``$external`` for the ``MONGODB-X509`` mechanism, and the
+         database name or ``$external`` for the ``PLAIN`` mechanism.
+
+   * - **compressors**
+     - A comma-separated list of strings
+     - None
+     - Specifies data compressors that the {+php-library+} uses to reduce the
+       amount of network data passed between MongoDB and your application in
+       the specified order.
+
+   * - **connectTimeoutMS**
+     - Non-negative integer
+     - ``10000`` (10 seconds)
+     - Specifies the connection timeout, in milliseconds, passed to each
+       underlying TCP stream when attempting to connect to the server.
+
+   * - **directConnection**
+     - Boolean
+     - ``false``
+     - Specifies whether to directly connect to a single host instead of
+       discovering and connecting to all servers in the cluster.
+
+   * - **heartbeatFrequencyMS**
+     - Integer greater than or equal to ``500``
+     - ``10000`` (10 seconds)
+     - Specifies the time in milliseconds that each monitoring thread
+       waits between performing server checks.
+
+   * - **journal**
+     - Boolean
+     - ``false``
+     - Requests acknowledgment that the operation propagated to the on-disk
+       journal.
+
+   * - **localThresholdMS**
+     - Non-negative integer
+     - ``15``
+     - | Specifies the time in milliseconds that the average round-trip time
+         between the driver and server can last compared to the shortest
+         round-trip time of all the suitable servers.
+       | A value of ``0`` indicates no latency window, so only the server with
+         the lowest average round-trip time is eligible.
+
+   * - **maxIdleTimeMS**
+     - Non-negative integer
+     - ``0``
+     - | Specifies the time in milliseconds that a connection can remain idle
+         in a connection pool before the server closes it.
+       | A value of ``0`` indicates that the client does not close idle
+         connections.
+
+   * - **maxStalenessSeconds**
+     - ``-1``, or any integer greater than or equal to ``90``
+     - ``-1``
+     - | Specifies the maximum lag, in seconds, behind the primary node
+         that a secondary node can be considered for the given operation.
+       | This option's value must be at least ``90``, or the operation raises
+         an error. A value of ``-1`` means there is no maximum lag.
+
+   * - **maxPoolSize**
+     - Non-negative integer
+     - ``10``
+     - | Specifies the maximum number of connections that the {+php-library+}
+         can create in a connection pool for a given server.
+       | If you attempt an operation while the value of ``maxPoolSize``
+         connections are checked out, the operation waits until an
+         in-progress operation finishes and the connection returns to the pool.
+
+   * - **minPoolSize**
+     - Non-negative integer
+     - ``0``
+     - | Specifies the minimum number of connections available in a server's
+         connection pool at a given time.
+       | If fewer than ``minPoolSize`` connections are in the pool,
+         the server adds connections in the background up to the value of ``minPoolSize``.
+
+   * - **readConcernLevel**
+     - String
+     - None
+     - Specifies the default read concern for operations performed by the
+       {+php-library+}.
+       To learn more, see :manual:`Read Concern </reference/read-concern/>` in the {+server-docs-name+}.
+
+   * - **readPreference**
+     - String
+     - ``primary``
+     - Specifies how the {+php-library+} routes a read operation to replica set
+       members.
+       To learn more, see :manual:`Read Preference </core/read-preference>` in the {+server-docs-name+}.
+
+   * - **readPreferenceTags**
+     - A list of comma-separated key-value pairs
+     - None
+     - Specifies which replica set members are considered for operations.  Each
+       instance of this key is a separate tag set. The driver checks each tag
+       set until it finds one or more servers with each tag.
+
+   * - **replicaSet**
+     - String
+     - None
+     - Specifies the name of the replica set the {+php-library+} connects to.
+
+   * - **retryReads**
+     - Boolean
+     - ``true``
+     - Specifies whether the {+php-library+} retries a read operation if the operation fails.
+
+   * - **serverSelectionTimeoutMS**
+     - Non-negative integer
+     - ``30000`` (30 seconds)
+     - Specifies the time in milliseconds that {+php-library+} waits to
+       select a server for an operation before timing out.
+
+   * - **tls**
+     - Boolean
+     - ``false``
+     - | Specifies the TLS configuration for the {+php-library+} to use in its
+         connections with the server.
+       | By default, TLS is off.
+
+   * - **tlsAllowInvalidCertificates**
+     - Boolean
+     - ``false``
+     - | Specifies whether the {+php-library+} returns an error if the server
+         presents an invalid certificate.
+       | We recommend setting this option to ``true`` only in testing
+         environments to avoid creating security vulnerabilities in your
+         application.
+
+   * - **tlsCAFile**
+     - String
+     - See description
+     - | Specifies the path to the certificate authority (CA) file that
+         the {+php-library+} uses for TLS.
+       | If you do not specify this option, the driver uses the Mozilla
+         root certificates from the ``webpki-roots`` crate.
+
+   * - **tlsCertificateKeyFile**
+     - String
+     - None
+     - | Specifies the path to the certificate file that {+php-library+}
+         presents to the server to verify its identity.
+       | If you do not set this option, the {+php-library+} does not
+         attempt to verify its identity with the server.
+
+   * - **tlsInsecure**
+     - Boolean
+     - ``false``
+     - | Specifies whether the {+php-library+} returns an error if the server
+         presents an invalid certificate.
+       | We recommend setting this option to ``true`` only in testing
+         environments to avoid creating security vulnerabilities in your
+         application.
+
+   * - **w**
+     - Non-negative integer or string
+     - None
+     - | Requests acknowledgment that the operation has propagated to a
+         specific number or variety of servers.
+       | To learn more, see :manual:`Write Concern </reference/write-concern>`
+         in the Server manual.
+
+   * - **wTimeoutMS**
+     - Non-negative integer
+     - No timeout
+     - Specifies a time limit, in milliseconds, of the write concern.
+       If an operation has not propagated to the requested level within the
+       time limit, the {+php-library+} raises an error.
+
+   * - **zlibCompressionLevel**
+     - Integer between ``-1`` and ``9`` (inclusive)
+     - ``-1``
+     - | Specifies the level field of the ``zlib`` compression if you use that compressor.
+       | Setting a value of ``-1`` selects the default compression level (``6``).
+       | Setting a value of ``0`` specifies no compression, and setting
+         a value of ``9`` specifies maximum compression.
+
+To see a full list of connection options, see the :manual:`Connection String Options
+</reference/connection-string/#connection-string-options>` section of the
+Connection Strings guide in the {+server-docs-name+}. Select ``PHP`` from the
+:guilabel:`Select your language` dropdown menu on the right side of the page.
+
+.. _laravel-driver-options:
+
+Driver Connection Options
+-------------------------
+
+Driver options modify the behavior of the {+php-library+}, which manages
+connections and all operations between a Laravel application and MongoDB.
+
+You can specify driver options in your Laravel web application's
+``config/database.php`` configuration file. To add driver options,
+add the setting and value as an array item in the ``driverOptions`` array
+item, as shown in the following example:
+
+.. code-block:: php
+   :emphasize-lines: 6-9
+
+   'connections' => [
+       'mongodb' => [
+           'dsn' => 'mongodb+srv://mongodb0.example.com/',
+           'driver' => 'mongodb',
+           'database' => 'sample_mflix',
+           'driverOptions' => [
+               'serverApi' => 1,
+               'allow_invalid_hostname' => false,
+           ],
+       ],
+   ]
+
+See the `$driverOptions: array <https://www.mongodb.com/docs/php-library/current/reference/method/MongoDBClient__construct/#parameters>`__
+section of the {+php-library+} documentation for a list of driver options.