Docs Menu
Docs Home
/
Languages
/
PHP
/
PHP Library Manual
/
Connect to MongoDB

Specify Connection Options

On this page

  • Overview
  • Set Connection Options
  • Using the Connection URI
  • Using a MongoDB\Client Object
  • Connection URI Options
  • Replica Set Options
  • Connection Options
  • Write Concern Options
  • Read Concern Options
  • Read Preference Options
  • Authentication Options
  • Server Selection and Discovery Options
  • Miscellaneous Configuration
  • API Documentation

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
Data Type: bool
MongoDB\Client Example: $uriOptions = ['directConnection' => true];
Connection URI Example: directConnection=true
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
Data Type: int
MongoDB\Client Example: $uriOptions = ['connectTimeoutMS' => 2000];
Connection URI Example: connectTimeoutMS=2000
Data Type: int
MongoDB\Client Example: $uriOptions = ['socketTimeoutMS' => 20000];
Connection URI Example: socketTimeoutMS=20000

Compression Options

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

Write Concern Options

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

Read Concern Options

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

Read Preference Options

Connection Option
Description
Data Type: MongoDB\Driver\ReadPreference
MongoDB\Client Example: $uriOptions = ['readPreference' => 'secondaryPreferred'];
Connection URI Example: readPreference=secondaryPreferred
Data Type: int
MongoDB\Client Example: $uriOptions = ['maxStalenessSeconds' => 30];
Connection URI Example: maxStalenessSeconds=30
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
Data Type: int
MongoDB\Client Example: $uriOptions = ['localThresholdMS' => 20];
Connection URI Example: localThresholdMS=20
Data Type: int
MongoDB\Client Example: $uriOptions = ['serverSelectionTimeoutMS' => 5000];
Connection URI Example: serverSelectionTimeoutMS=5000
Data Type: bool
MongoDB\Client Example: $uriOptions = ['serverSelectionTryOnce' => false];
Connection URI Example: serverSelectionTryOnce=false
Data Type: int
MongoDB\Client Example: $uriOptions = ['heartbeatFrequencyMS' => 30000];
Connection URI Example: heartbeatFrequencyMS=30000
Data Type: int
MongoDB\Client Example: $uriOptions = ['socketCheckIntervalMS' => 4000];
Connection URI Example: socketCheckIntervalMS=4000

Miscellaneous Configuration

Connection Option
Description
Data Type: string
MongoDB\Client Example: $uriOptions = ['appName' => 'myApp'];
Connection URI Example: appName=myApp
Data Type: bool
MongoDB\Client Example: $uriOptions = ['retryReads' => false];
Connection URI Example: retryReads=false
Data Type: bool
MongoDB\Client Example: $uriOptions = ['retryWrites' => false];
Connection URI Example: retryWrites=false
Data Type: bool
MongoDB\Client Example: $uriOptions = ['loadBalanced' => true];
Connection URI Example: loadBalanced=true
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:

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

Back

Create a Client

Next

Choose a Connection Target