For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Docs Menu
Docs Home
/ /
Connect
Docs Home
/ /
PHP Library
/
Connect
Docs Home
/
Client Libraries
/
PHP
/
PHP Library
/
Connect

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:

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
Note: This option is supported only on MongoDB 9.0 or later.

maxAdaptiveRetries

Data Type: int
MongoDB\Client Example: $uriOptions = ['maxAdaptiveRetries' => 3];
Connection URI Example: maxAdaptiveRetries=3
Note: This option is supported only on MongoDB 9.0 or later.

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

Note

Load Shedding in Intelligent Workload Management (IWM)

If errors with SystemOverloadedError or RetryableError labels are causing failures in your application or appearing in your application logs, Load Shedding may be active on your cluster and your driver may not be upgraded to a version that supports it. We recommend upgrading your MongoDB PHP Library to version 2.3 or later. If you continue to see these errors after upgrading, you can address them through server-side changes, such as reviewing your Load Shedding configuration, or through application-side changes, such as implementing custom error handling or client-side request throttling. Depending on your situation, application-side changes may be preferable or necessary.

Load Shedding is a feature of IWM, and helps manage server load by rejecting excess operations during sustained overload. This feature is available on MongoDB 9.0 and later.

For more information about IWM or handling overload errors, see the Intelligent Workload Management page or Overload Errors page in the Atlas documentation.

API Documentation

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

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

Back
Choose a Connection Target
Next
Stable API
Rate this page

On this page