Connection Options

On this page

Overview

Connection and Authentication Options
Add Connection and Authentication Options
Option Descriptions
Driver Connection Options

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 MongoDB PHP Library, which manages your database connections.

To learn more about the MongoDB PHP Library, see the MongoDB PHP Library documentation.

This guide covers the following topics:

Connection and Authentication Options
Driver Connection Options

Connection and Authentication Options

Learn how to add common connection and authentication options to your configuration file in the following sections:

Add Connection and Authentication Options
Option Descriptions

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:

'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:

'dsn' => 'mongodb+srv://mongodb0.example.com/?appName=myLaravelApp&compressors=zlib',

Option Descriptions

The following table describes a list of connection and authentication options and their default values:

Option Name	Accepted Values	Default Value	Description
appName	String	None	Specifies the application name that the MongoDB 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 Authentication in the Server manual.
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 MongoDB 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. To learn more about this setting, see Direct Connection in the Connection Guide.
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 MongoDB 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 MongoDB PHP Library. To learn more, see Read Concern in the Server manual.
readPreference	String	`primary`	Specifies how the MongoDB PHP Library routes a read operation to replica set members. To learn more, see Read Preference in the Server manual.
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 MongoDB PHP Library connects to.
retryReads	Boolean	`true`	Specifies whether the MongoDB PHP Library retries a read operation if the operation fails.
serverSelectionTimeoutMS	Non-negative integer	`30000` (30 seconds)	Specifies the time in milliseconds that MongoDB PHP Library waits to select a server for an operation before timing out.
tls	Boolean	`false`	Specifies the TLS configuration for the MongoDB PHP Library to use in its connections with the server. By default, TLS is off.
tlsAllowInvalidCertificates	Boolean	`false`	Specifies whether the MongoDB 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 MongoDB 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 MongoDB PHP Library presents to the server to verify its identity. If you do not set this option, the MongoDB PHP Library does not attempt to verify its identity with the server.
tlsInsecure	Boolean	`false`	Specifies whether the MongoDB 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 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 MongoDB 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 Connection String Options section of the Connection Strings guide in the Server manual. Select PHP from the Select your language dropdown menu on the right side of the page.

Driver Connection Options

Driver options modify the behavior of the MongoDB 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:

'connections' => [
    'mongodb' => [
        'dsn' => 'mongodb+srv://mongodb0.example.com/',
        'driver' => 'mongodb',
        'database' => 'sample_mflix',
        'driverOptions' => [
            'serverApi' => 1,
            'allow_invalid_hostname' => false,
        ],
    ],
]

See the $driverOptions: array section of the MongoDB PHP Library documentation for a list of driver options.

Back

Connection Guide

Enable and Configure TLS