Create new MongoDB Manager

Description

final public MongoDB\Driver\Manager::__construct ([ string $uri = "mongodb://127.0.0.1/ [, array $uriOptions = [] [, array $driverOptions = [] ]]] )

Constructs a new MongoDB\Driver\Manager object with the specified options.

Note: Per the » Server Discovery and Monitoring Specification, this constructor performs no I/O. Connections will be initialized on demand, when the first operation is executed.

Tip

On Unix platforms, the MongoDB driver is sensitive to scripts that use the fork() system call without also calling exec(). Users are advised not to re-use MongoDB\Driver\Manager instances in a forked child process.

Parameters

uri

A » mongodb:// connection URI:

mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]

For details on supported options, see » Connection String Options in the MongoDB manual. » Connection pool options are not supported, as the PHP driver does not implement connection pools.

The uri is a URL, hence any special characters in its components need to be URL encoded according to » RFC 3986. This is particularly relevant to the username and password, which can often include special characters such as @, :, or %. When connecting via a Unix domain socket, the socket path may contain special characters such as slashes and must be encoded. The rawurlencode() function may be used to encode constituent parts of the URI.

uriOptions

Additional » connection string options, which will overwrite any options with the same name in the uri parameter.

**uriOptions**
Option	Type	Description
authMechanism	string	The authentication mechanism that MongoDB will use to authenticate the connection. For details, see » Authentication Options in the MongoDB manual.
authSource	string	The database name associated with the user's credentials. Defaults to the database component of the connection URI. For authentication mechanisms that delegate credential storage to other services (e.g. GSSAPI), this should be "$external".
connectTimeoutMS	integer	The time in milliseconds to attempt a connection before timing out. Defaults to 10 seconds.
gssapiServiceName	string	Set the Kerberos service name when connecting to Kerberized MongoDB instances. This value must match the service name set on MongoDB instances (i.e. » saslServiceName server parameter). Defaults to "mongodb".
journal	boolean	Corresponds to the write concern's `journal` parameter. If `TRUE`, writes will require acknowledgement from MongoDB that the operation has been written to the journal. For details, see MongoDB\Driver\WriteConcern.
maxStalenessSeconds	integer	Corresponds to the read preference's "maxStalenessSeconds". Specifies, in seconds, how stale a secondary can be before the client stops using it for read operations. By default, there is no maximum staleness and clients will not consider a secondary’s lag when choosing where to direct a read operation. For details, see MongoDB\Driver\ReadPreference.
password	string	The password for the user being authenticated. This option is useful if the password contains special characters, which would otherwise need to be URL encoded for the connection URI.
readConcernLevel	string	Corresponds to the read concern's `level` parameter. Specifies the level of read isolation. For details, see MongoDB\Driver\ReadConcern.
readPreference	string	Corresponds to the read preferences's `mode` parameter. Defaults to "primary". For details, see MongoDB\Driver\ReadPreference. Note: This accepts a string value (e.g. "primary", "secondaryPreferred"), unlike MongoDB\Driver\ReadPreference::__construct(), which takes an integer.
readPreferenceTags	array	Corresponds to the read preferences's `tagSets` parameter. Tag sets allow you to target read operations to specific members of a replica set. For details, see MongoDB\Driver\ReadPreference. Note: When not specified in the URI string, this option is expressed as an array consistent with the format expected by MongoDB\Driver\ReadPreference::__construct().
replicaSet	string	Specifies the name of the replica set.
safe	boolean	Specifies 1 for the write concern if `TRUE`, or 0 if `FALSE` For details, see MongoDB\Driver\WriteConcern. This option is deprecated and should not be used.
slaveOk	boolean	Specifies "secondaryPreferred" for the read preference mode if `TRUE`. For details, see MongoDB\Driver\ReadPreference. This option is deprecated and should not be used.
socketTimeoutMS	integer	The time in milliseconds to attempt a send or receive on a socket before the attempt times out. Defaults to 300 seconds (i.e. five minutes).
ssl	boolean	Initiates the connection with TLS/SSL if `TRUE`. Defaults to `FALSE`.
username	string	The username for the user being authenticated. This option is useful if the username contains special characters, which would otherwise need to be URL encoded for the connection URI.
w	integer\|string	Corresponds to the write concern's `w` parameter. For details, see MongoDB\Driver\WriteConcern.
wTimeoutMS	integer\|string	Corresponds to the write concern's `wtimeout` parameter. Specifies a time limit, in milliseconds, for the write concern. For details, see MongoDB\Driver\WriteConcern.

driverOptions

**driverOptions**
Option	Type	Description
allow_invalid_hostname	bool	Disables hostname validation if `TRUE`. Defaults to `FALSE`. Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.
ca_dir	string	Path to a correctly hashed certificate directory. The system certificate store will be used by default. Falls back to the deprecated "capath" SSL context option if not specified.
ca_file	string	Path to a certificate authority file. The system certificate store will be used by default. Falls back to the deprecated "cafile" SSL context option if not specified.
crl_file	string	Path to a certificate revocation list file.
pem_file	string	Path to a PEM encoded certificate to use for client authentication. Falls back to the deprecated "local_cert" SSL context option if not specified.
pem_pwd	string	Passphrase for the PEM encoded certificate (if applicable). Falls back to the deprecated "passphrase" SSL context option if not specified.
context	resource	SSL context options to be used as fallbacks for other driver options (as specified). Note that the driver does not consult the default stream context. This option is supported for backwards compatibility, but should be considered deprecated.
weak_cert_validation	bool	Disables certificate validation if `TRUE`. Defaults to `FALSE` Falls back to the deprecated "allow_self_signed" SSL context option if not specified.

Errors/Exceptions

Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
Throws MongoDB\Driver\Exception\RuntimeException if the uri format is invalid

Changelog

Version Description

1.2.0

Version	Description
1.2.0	The `uri` argument defaults to "mongodb://127.0.0.1/". The default port remains 27017. Added the "allow_invalid_hostname", "ca_file", "ca_dir", "clr_file", "pem_file", "pem_pwd", and "weak_cert_validation" driver options. The driver no longer supports all SSL context options via the "context" driver option, since the PHP Streams API is no longer used for socket communication.
1.1.0	The `uri` argument is optional and defaults to "mongodb://localhost:27017/".

The uri argument defaults to "mongodb://127.0.0.1/". The default port remains 27017.

Added the "allow_invalid_hostname", "ca_file", "ca_dir", "clr_file", "pem_file", "pem_pwd", and "weak_cert_validation" driver options.

The driver no longer supports all SSL context options via the "context" driver option, since the PHP Streams API is no longer used for socket communication.

1.1.0

The uri argument is optional and defaults to "mongodb://localhost:27017/".

Examples

Example #1 MongoDB\Driver\Manager::__construct() basic examples

Connecting to standalone MongoDB node:


<?php

$manager = new MongoDB\Driver\Manager("mongodb://example.com:27017");

?>

Connecting to standalone MongoDB node via a Unix domain socket. The socket path may include special characters such as slashes and should be encoded with rawurlencode().


<?php

$manager = new MongoDB\Driver\Manager("mongodb://" . rawurlencode("/tmp/mongodb-27017.sock"));

?>

Connecting to a replica set:


<?php

$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

?>

Connecting to a sharded cluster (i.e. one or more mongos instances):


<?php

$manager = new MongoDB\Driver\Manager("mongodb://mongos1.example.com,mongos2.example.com/");

?>

Connecting to MongoDB with authentication credentials for a particular user and database:


<?php

$manager = new MongoDB\Driver\Manager("mongodb://myusername:mypassword@example.com/mydatabase");

?>

Connecting to MongoDB with authentication credentials for a particular user and database, where the username or password includes special characters (e.g. @, :, %). In the following example, the password string myp@ss:w%rd has been manually escaped; however, rawurlencode() may also be used to escape URI components that may contain special characters.


<?php

$manager = new MongoDB\Driver\Manager("mongodb://myusername:myp%40ss%3Aw%25rd@example.com/mydatabase");

?>

Connecting to MongoDB with X509 authentication:


<?php

$manager = new MongoDB\Driver\Manager(
    "mongodb://example.com/?ssl=true&authMechanism=MONGODB-X509",
    [],
    [
        "pem_file" => "/path/to/client.pem",
    ]
);
?>