/ /

Specify Connection Options

Overview

This page describes the MongoDB connection and authentication options available in the PHP library.

Set Connection Options

You can configure your connection by specifying options in the connection URI or by passing them to the MongoDB\Client constructor.

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:

// 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);

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:

// 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);

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 MongoDB Server manual.

Important

Percent-Encoding

If the value of a connection option contains special characters, you must percent-encode 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
rawurlencode in the PHP manual

Replica Set Options

Connection Option	Description
directConnection	Data Type: `bool` MongoDB\Client Example: `$uriOptions = ['directConnection' => true];` Connection URI Example: `directConnection=true`
replicaSet	Data Type: `string` MongoDB\Client Example: `$uriOptions = ['replicaSet' => 'replicaSetName'];` Connection URI Example: `replicaSet=replicaSetName`

Connection Options

TLS Options

To learn about the TLS options available in the PHP library, see the TLS page.

Timeout Options

Connection Option	Description
connectTimeoutMS	Data Type: `int` MongoDB\Client Example: `$uriOptions = ['connectTimeoutMS' => 2000];` Connection URI Example: `connectTimeoutMS=2000`
socketTimeoutMS	Data Type: `int` MongoDB\Client Example: `$uriOptions = ['socketTimeoutMS' => 20000];` Connection URI Example: `socketTimeoutMS=20000`

Compression Options

Connection Option	Description
compressors	Data Type: `string` MongoDB\Client Example: `$uriOptions = ['compressors' => 'snappy,zstd,zlib'];` Connection URI Example: `compressors=snappy,zstd,zlib`
zlibCompressionLevel	Data Type: `int` MongoDB\Client Example: `$uriOptions = ['zlibCompressionLevel' => 3];` Connection URI Example: `zlibCompressionLevel=3`

Write Concern Options

Connection Option	Description
w	Data Type: `string` MongoDB\Client Example: `$uriOptions = ['w' => 'majority'];` Connection URI Example: `w=majority`
wTimeoutMS	Data Type: `int` MongoDB\Client Example: `$uriOptions = ['wTimeoutMS' => 10000];` Connection URI Example: `wTimeoutMS=10000`
journal	Data Type: `bool` MongoDB\Client Example: `$uriOptions = ['journal' => true];` Connection URI Example: `journal=true`

Read Concern Options

Connection Option	Description
readConcernLevel	Data Type: `string` MongoDB\Client Example: `$uriOptions = ['readConcernLevel' => 'majority'];` Connection URI Example: `readConcernLevel=majority`

Read Preference Options

Connection Option

Description

readPreference

Data Type: MongoDB\Driver\ReadPreference
MongoDB\Client Example: $uriOptions = ['readPreference' => 'secondaryPreferred'];
Connection URI Example: readPreference=secondaryPreferred

maxStalenessSeconds

Data Type: int
MongoDB\Client Example: $uriOptions = ['maxStalenessSeconds' => 30];
Connection URI Example: maxStalenessSeconds=30

readPreferenceTags

Data Type: array
MongoDB\Client Example:

$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 PHP library, see Authentication Mechanisms.

Server Selection and Discovery Options

Connection Option	Description
localThresholdMS	Data Type: `int` MongoDB\Client Example: `$uriOptions = ['localThresholdMS' => 20];` Connection URI Example: `localThresholdMS=20`
serverSelectionTimeoutMS	Data Type: `int` MongoDB\Client Example: `$uriOptions = ['serverSelectionTimeoutMS' => 5000];` Connection URI Example: `serverSelectionTimeoutMS=5000`
serverSelectionTryOnce	Data Type: `bool` MongoDB\Client Example: `$uriOptions = ['serverSelectionTryOnce' => false];` Connection URI Example: `serverSelectionTryOnce=false`
heartbeatFrequencyMS	Data Type: `int` MongoDB\Client Example: `$uriOptions = ['heartbeatFrequencyMS' => 30000];` Connection URI Example: `heartbeatFrequencyMS=30000`
socketCheckIntervalMS	Data Type: `int` MongoDB\Client Example: `$uriOptions = ['socketCheckIntervalMS' => 4000];` Connection URI Example: `socketCheckIntervalMS=4000`
`enableOverloadRetargeting`	Data Type: `bool` MongoDB\Client Example: `$uriOptions = ['enableOverloadRetargeting' => true];` Connection URI Example: `enableOverloadRetargeting=true`
`maxAdaptiveRetries`	Data Type: `int` MongoDB\Client Example: `$uriOptions = ['maxAdaptiveRetries' => 3];` Connection URI Example: `maxAdaptiveRetries=3`

Miscellaneous Configuration

Connection Option	Description
appName	Data Type: `string` MongoDB\Client Example: `$uriOptions = ['appName' => 'myApp'];` Connection URI Example: `appName=myApp`
retryReads	Data Type: `bool` MongoDB\Client Example: `$uriOptions = ['retryReads' => false];` Connection URI Example: `retryReads=false`
retryWrites	Data Type: `bool` MongoDB\Client Example: `$uriOptions = ['retryWrites' => false];` Connection URI Example: `retryWrites=false`
loadBalanced	Data Type: `bool` MongoDB\Client Example: `$uriOptions = ['loadBalanced' => true];` Connection URI Example: `loadBalanced=true`
srvMaxHosts	Data Type: `int` MongoDB\Client Example: `$uriOptions = ['srvMaxHosts' => 5];` Connection URI Example: `srvMaxHosts=5`

API Documentation

For more information about the MongoDB\Client class, see the following PHP library API documentation:

MongoDB\Client

For more information about the MongoDB\Driver\ReadPreference class, see the following PHP extension API documentation:

MongoDB\Driver\ReadPreference

Back

Choose a Connection Target

Stable API