Connect to MongoDB
On this page
- Overview
- Sample Application
- Connection
- Atlas
- Local Deployment
- Replica Set
- Transport Layer Security (TLS)
- Enable TLS
- Specify a Certificate Authority (CA) File
- Disable OCSP Checks
- Specify a Certificate Revocation List (CRL)
- Present a Client Certificate
- Provide a Certificate Key File Password
- Allow Insecure TLS
- Disable Certificate Validation
- Disable Hostname Verification
- Stable API
Overview
This page contains code examples that show how to connect your PHP application to MongoDB with various settings.
Tip
To learn more about the connection options on this page, see the link provided in each section.
To use a connection example from this page, copy the code example into the
sample application or your own application.
Make sure to replace all placeholders in the code examples, such as
<hostname>
, with the relevant values for your MongoDB deployment.
Sample Application
You can use the following sample application to test the code examples on this page. To use the sample application, perform the following steps:
Ensure you have the MongoDB PHP Library installed in your project. To learn more about installing the MongoDB PHP Library, see the Download and Install guide.
Copy the following code and paste it into a new
.php
file.Copy a code example from this page and paste it on the specified lines in the file.
1 2 3 require __DIR__ . '/../vendor/autoload.php'; 4 5 // Start example code here 6 7 // End example code here 8 9 try { 10 $client->test->command(['ping' => 1]); 11 echo 'Successfully pinged the MongoDB server.', PHP_EOL; 12 } catch (MongoDB\Driver\Exception\RuntimeException $e) { 13 printf("Failed to ping the MongoDB server: %s\n", $e->getMessage()); 14 }
Important
Percent-Encoding
You must percent-encode a username and password before
you include them in a MongoDB URI. You can use the rawurlencode()
method to encode
these values according to the URI syntax specified in RFC 3986.
Don't percent-encode the username or password when passing them in an options array
parameter to the MongoDB\Client
constructor.
Connection
Atlas
The following code shows how to connect to a MongoDB Atlas deployment:
$uri = '<Atlas connection string>'; $client = new MongoDB\Client($uri);
To learn more about connecting to an Atlas deployment, see Atlas in the Connection Targets guide.
Local Deployment
The following code shows how to connect to a local MongoDB deployment:
$uri = 'mongodb://localhost:27017/'; $client = new MongoDB\Client($uri);
Note
If you don't specify the $uri
parameter, the connection URI defaults to
'mongodb://127.0.0.1:27017'
.
To learn more about connecting to a local deployment, see Local Deployments in the Connection Targets guide.
Replica Set
The following code shows how to connect to a replica set deployment:
$client = new MongoDB\Client( 'mongodb://<replica set member>:<port>/', ['replicaSet' => '<replica set name>'], );
$uri = 'mongodb://<replica set member>:<port>/?replicaSet=<replica set name>'; $client = new MongoDB\Client($uri);
Tip
To maintain your connection to a replica set deployment when one host is down, you can provide multiple replica set members in the connection URI.
To learn more about connecting to a replica set, see Replica Sets in the Connection Targets guide.
Transport Layer Security (TLS)
Enable TLS
The following code shows how to enable TLS for the connection to your MongoDB instance:
$client = new MongoDB\Client( 'mongodb://<hostname>:<port>/', ['tls' => true], );
$uri = 'mongodb://<hostname>:<port>/?tls=true'; $client = new MongoDB\Client($uri);
To learn more about enabling TLS, see Enable TLS in the TLS Configuration guide.
Specify a Certificate Authority (CA) File
The following code shows how to specify the path to your CA file for the connection to your MongoDB instance:
$client = new MongoDB\Client( 'mongodb://<hostname>:<port>/', ['tls' => true, 'tlsCAFile' => '/path/to/ca.pem'], );
$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCAFile=/path/to/ca.pem'; $client = new MongoDB\Client($uri);
To learn more about specifying a CA file, see Specify a CA File in the TLS Configuration guide.
Disable OCSP Checks
The following code shows how to prevent the driver from contacting the OCSP endpoint:
$client = new MongoDB\Client( 'mongodb://<hostname>:<port>/', ['tls' => true, 'tlsDisableOCSPEndpointCheck' => true], );
$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsDisableOCSPEndpointCheck=true'; $client = new MongoDB\Client($uri);
To learn more about disabling OCSP checks, see OCSP in the TLS Configuration guide.
Specify a Certificate Revocation List (CRL)
The following code shows how to instruct the driver to verify the server's certificate against a CRL:
$client = new MongoDB\Client( 'mongodb://<hostname>:<port>/', ['tls' => true], ['crl_file' => '/path/to/file.pem'], );
To learn more about specifying a CRL, see Certificate Revocation List in the TLS configuration guide.
Present a Client Certificate
The following code shows how to specify the client certificate that the driver presents to your MongoDB deployment:
$client = new MongoDB\Client( 'mongodb://<hostname>:<port>/', ['tls' => true, 'tlsCertificateKeyFile' => '/path/to/client.pem'], );
$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/client.pem'; $client = new MongoDB\Client($uri);
To learn more about specifying a client certificate, see Present a Client Certificate in the TLS Configuration guide.
Provide a Certificate Key File Password
The following code shows how to specify the password for your client certificate:
$client = new MongoDB\Client( 'mongodb://<hostname>:<port>/', [ 'tls' => true, 'tlsCertificateKeyFile' => '/path/to/client.pem', 'tlsCertificateKeyFilePassword' => '<password>' ], );
$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/client.pem&tlsCertificateKeyFilePassword=<password>'; $client = new MongoDB\Client($uri);
Important
When replacing the <password>
placeholder in the connection URI, ensure
that you percent-encode the value.
To learn more about providing a key file password, see Provide a Key Password in the TLS Configuration guide.
Allow Insecure TLS
The following code shows how to relax TLS constraints, which has the same effect as disabling both certificate validation and hostname verification:
$client = new MongoDB\Client( 'mongodb://<hostname>:<port>/', ['tls' => true, 'tlsInsecure' => true], );
$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsInsecure=true'; $client = new MongoDB\Client($uri);
To learn more about allowing insecure TLS, see Allow Insecure TLS in the TLS Configuration guide.
Warning
Setting the tlsInsecure
option to true
might expose your application
to security risks. Enabling this option makes your application insecure and
potentially vulnerable to expired certificates and to foreign processes posing
as valid client instances.
Disable Certificate Validation
The following code shows how to disable certificate validation:
$client = new MongoDB\Client( 'mongodb://<hostname>:<port>/', ['tls' => true, 'tlsAllowInvalidCertificates' => true], );
$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsAllowInvalidCertificates=true'; $client = new MongoDB\Client($uri);
To learn more about disabling certificate validation, see Allow Insecure TLS in the TLS Configuration guide.
Disable Hostname Verification
The following code shows how to disable hostname verification:
$client = new MongoDB\Client( 'mongodb://<hostname>:<port>/', ['tls' => true, 'tlsAllowInvalidHostnames' => true], );
$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsAllowInvalidHostnames=true'; $client = new MongoDB\Client($uri);
To learn more about disabling hostname verification, see Allow Insecure TLS in the TLS Configuration guide.
Stable API
The following code shows how to enable the Stable API for the connection to your MongoDB instance:
$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1')]; $client = new MongoDB\Client( 'mongodb://<hostname>:<port>/', [], $driverOptions, );
To learn more about the Stable API, see the Stable API guide.