Create a MongoDB Client

Overview

To connect to a MongoDB deployment, you must create the following items:

• Connection URI, also known as a connection string, which tells the PHP library which MongoDB deployment to connect to.

• MongoDB\Client object, which creates the connection to the MongoDB deployment and lets you perform operations on it.

You can also set options within either or both of these components to customize the way that the PHP library behaves while connected to MongoDB.

This guide describes the components of a connection string and shows how to use a MongoDB\Client object to connect to a MongoDB deployment.

Connection URI

A standard connection string includes the following components:

To learn more about connection strings, see Connection Strings in the Server manual.

Create a MongoDB\Client

To create a connection to MongoDB, construct a MongoDB\Client object. Pass the following parameters to the MongoDB\Client constructor:

• $uri: Sets the connection URI.

• $uriOptions: (Optional) Sets URI options to configure how the client connects to MongoDB, including authentication credentials and server selection settings. If you set the same options in this parameter and in your connection string, the $uriOptions values take precedence. To view a full list of supported options, see the Specify Connection Options guide.

• $driverOptions: (Optional) Sets options to configure the behavior of the underlying PHP extension, including data encryption settings and certificate validation options for TLS connections. To view a full list of supported options, see MongoDB\Client::__construct() in the API documentation.

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

Client Persistence

The libmongoc library and the PHP extension handle connections to a MongoDB deployment. When you construct a MongoDB\Client instance, the PHP library creates a MongoDB\Driver\Manager instance by using the same connection string and options. The extension also uses those constructor arguments to derive a hash key for persistent libmongoc clients. If you previously persisted a libmongoc client by using a key, it is reused. Otherwise, a new libmongoc client is created and persisted for the lifetime of the PHP worker process. To learn more about this process, see the PHP extension documentation.

Each libmongoc client maintains its own connections to the MongoDB deployment and a view of its topology. When you reuse a persistent libmongoc client, the PHP library can avoid the overhead of establishing new connections and rediscovering the topology. This approach generally improves performance and is the driver's default behavior.

Persistent libmongoc clients are not freed until the PHP worker process ends. As a result, connections to a MongoDB deployment might remain open after a MongoDB\Driver\Manager object goes out of scope. While this is typically not an issue for applications that connect to one MongoDB deployment, it might cause errors in the following situations:

• PHP-FPM is configured with pm.max_requests=0 so workers never respawn, and a PHP application is deployed many times with small changes to its MongoDB connection string or options. This could lead to an accumulation of libmongoc client objects in each worker process.

• An application occasionally connects to a separate MongoDB deployment in a backend component where request latency is not the most important aspect.

In the first case, restarting PHP-FPM as part of the application deployment allows the application to release any unused libmongoc clients and still use a persistent client for the latest connection string.

The second case requires a different solution. Specifying true for the disableClientPersistence driver option instructs the PHP library to create a new libmongoc client and ensure it is freed when the corresponding MongoDB\Driver\Manager goes out of scope.

The following code demonstrates how to set the disableClientPersistence option to true when creating a client:

<?php
$client = new MongoDB\Client(
    uri: getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/',
    driverOptions: ['disableClientPersistence' => true],
);

API Documentation

To learn more about creating a MongoDB\Client object in the PHP library, see the following API documentation:

• MongoDB\Client