Choose a Connection Target

Overview

In this guide, you can learn how to use a connection string and MongoDB\Client object to connect to different types of MongoDB deployments.

Atlas

To connect to a MongoDB deployment on Atlas, include the following elements in your connection string:

• URI of your Atlas cluster

• Database username

• Database user's password

Then, pass your connection string to the MongoDB\Client constructor.

When you connect to Atlas, we recommend using the Stable API client option to avoid breaking changes when Atlas upgrades to a new version of MongoDB Server. To learn more about the Stable API feature, see the Stable API page.

The following code shows how to use the PHP library to connect to an Atlas cluster. The code also uses the serverApi option to specify a Stable API version.

<?php
// Replace the placeholder with your Atlas connection string
$uri = '<connection string>';
// Create a MongoDB client with server API options
$client = new MongoDB\Client($uri, [], [
    'serverApi' => new MongoDB\Driver\ServerApi('1'),
]);
// Ping the server to verify that the connection works
$admin = $client->admin;
$command = new MongoDB\Driver\Command(['ping' => 1]);
$result = $admin->command($command)->toArray();
echo json_encode($result), PHP_EOL;
echo 'Pinged your deployment. You successfully connected to MongoDB!\n';

Local Deployments

To connect to a local MongoDB deployment, use localhost as the hostname. By default, the mongod process runs on port 27017, though you can customize this for your deployment.

The following code shows how to use the PHP library to connect to a local MongoDB deployment:

<?php
$uri = 'mongodb://localhost:27017';
$uriOptions = ['serverSelectionTimeoutMS' => 10000];
$client = new MongoDB\Client($uri, $uriOptions);

Replica Sets

To connect to a replica set, specify the hostnames (or IP addresses) and port numbers of the replica set members in your connection string.

If you aren't able to provide a full list of hosts in the replica set, you can specify one or more of the hosts in the replica set and instruct the PHP library to perform automatic discovery to find the others. To instruct the driver to perform automatic discovery, choose one of the following actions:

• Specify the name of the replica set as the value of the replicaSet parameter.

• Specify false as the value of the directConnection parameter.

• Specify more than one host in the replica set.

In the following example, the driver uses a sample connection URI to connect to the MongoDB replica set sampleRS, which is running on port 27017 of three different hosts, including host1:

<?php
$uri = 'mongodb://host1:27017/?replicaSet=sampleRS';
// Create a MongoDB client
$client = new MongoDB\Client($uri);

<?php
// Replace the placeholders with your actual hostname and port
$uri = 'mongodb://<hostname>:<port>/?directConnection=true';
// Create a MongoDB client
$client = new MongoDB\Client($uri);

DNS Service Discovery

To use DNS service discovery to look up the DNS SRV record of the service you're connecting to, specify the SRV connection format in your connection string. If you specify this format, the PHP library automatically rescans for new hosts. Your deployment can add hosts to its topology without requiring changes in your client configuration.

The following code shows a connection string that uses the SRV connection format:

$uri = 'mongodb+srv://<hostname>/';

To learn more about the SRV connection format, see the SRV Connection Format entry in the MongoDB Server manual.

Server Selection Errors

The following code shows possible server selection error messages that your application might generate:

No suitable servers found (`serverSelectionTryOnce` set):
  [connection refused calling hello on 'a.example.com:27017']
  [connection refused calling hello on 'b.example.com:27017']
No suitable servers found: `serverSelectionTimeoutMS` expired:
  [socket timeout calling hello on 'example.com:27017']
No suitable servers found: `serverSelectionTimeoutMS` expired:
  [connection timeout calling hello on 'a.example.com:27017']
  [connection timeout calling hello on 'b.example.com:27017']
  [TLS handshake failed: -9806 calling hello on 'c.example.com:27017']
No suitable servers found: `serverselectiontimeoutms` timed out:
 [TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'a.example.com:27017']
 [TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'b.example.com:27017']

The PHP extension usually represents these errors as MongoDB\Driver\Exception\ConnectionTimeoutException exceptions. However, the exception messages originate from libmongoc, which is the underlying system library used by the extension. Since these messages can take many forms, we recommend breaking down the structure of the message so you can better diagnose errors in your application.

Messages typically start with "No suitable servers found". The next part of the message indicates how server selection failed. The extension avoids a server selection loop and makes a single attempt by default, according to the serverSelectionTryOnce connection string option. If the extension is configured to use a loop, a message that includes the phrase "serverSelectionTimeoutMS expired" indicates that you exhausted its time limit.

The last component of the message tells us why server selection failed and includes one or more errors directly from the topology scanner, which is the service responsible for connecting to and monitoring each host. Any host that previously experienced an error during monitoring will be included in this list. These messages typically originate from low-level socket or TLS functions.

The following list describes the possible meanings of common phrases in the last error message component:

• "Connection refused": The remote host might not be not listening on the expected port.

• "Connection timeout": There might be a routing problem, a firewall error, or a timeout due to latency.

• "Socket timeout": You likely established an initial connection that was dropped or timed out due to latency.

• "TLS handshake failed": TLS or OCSP verification did not succeed, and you might be using misconfigured TLS certificates.

In the case of a connection failure, you can use the connect tool for more troubleshooting information. This tool tries to connect to each host in a connection string by using socket functions, and then attempts to interact with data. If you used Composer to install the library, you can use the following command to start the connect tool:

php vendor/mongodb/mongodb/tools/connect.php <connection URI>

If the server you are connecting to does not accept connections, the output resembles the following code:

Looking up MongoDB at <connection URI>
Found 1 host(s) in the URI. Will attempt to connect to each.
Could not connect to <host>:<port>: Connection refused

API Documentation

To learn more about using the MongoDB\Client class, see the following API documentation:

• MongoDB\Client