(PECL mongoclient >=0.9.0)
MongoClient::__construct — Creates a new database connection object
$server = "mongodb://localhost:27017"
[, array $options = array("connect" => TRUE)
]] )If no parameters are passed, this connects to "localhost:27017" (or whatever was specified in php.ini for mongo.default_host and mongo.default_port).
server should have the form:
mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
The connection string always starts with mongodb://, to indicate it is a connection string in this form.
If username and password are specified, the constructor will attempt to authenticate the connection with the database before returning. Username and password are optional and must be followed by an @, if specified.
At least one host must be given (port optional, always defaulting to 27017) and as many hosts as desired may be connected to. Host names are comma-separated and the constructor will return successfully if it connected to at least one host. If it could not connect to any of the hosts, it will throw a MongoConnectionException.
If you specified a username and password, you may specify a database to authenticate with. If db is not specified, "admin" will be used.
An optional query string may be used to specify extra options. The same
options are supported through the options array as
well, and are therefore redescribed there.
One part of the options governs how the driver reads from secondary nodes in a replica set environment. Extra information on how these read preferences work is available as well through the read preferences documentation page.
server
The server name.
options
An array of options for the connection. Currently available options include:
"connect"
If the constructor should connect before returning. Default is
TRUE. When set to FALSE the driver will
automatically connection to the server whenever
it is necessary to do a query. Alternatively, you can run
MongoClient::connect() manually.
This option is not supported through the connection string.
"db"
The database to authenticate against can be specified here, instead of including it in the host list. This overrides a database given in the host list.
"password"
The password can be specified here, instead of including it in the host list. This is especially useful if a password has a "@" in it. This overrides a password set in the host list.
"readPreference"
Specifies the read preference type. Read preferences provide you with control from which secondaries data can be read from.
Allowed values are: MongoClient::RP_PRIMARY,
MongoClient::RP_PRIMARY_PREFERRED,
MongoClient::RP_SECONDARY,
MongoClient::RP_SECONDARY_PREFERRED and
MongoClient::RP_NEAREST.
See the documentation on read preferences for more information.
"readPreferenceTags"
Specifies the read preference tags as an array of strings. Tags can be used in combination with the readPreference option to further control which secondaries data might be read from.
See the documentation on read preferences for more information.
"replicaSet"
The name of the replica set to connect to. If this is given, the primary will be automatically be determined. This means that the driver may end up connecting to a server that was not even listed. See the replica set example below for details.
"timeout"
For how long the driver should try to connect to the database (in milliseconds).
"username"
The username can be specified here, instead of including it in the host list. This is especially useful if a username has a ":" in it. This overrides a username set in the host list.
"w"
The w option specifies the Write Concern for the driver, which determines how long the driver blocks when writing. The default value is 1.
This option is applicable when connecting to both single servers and replica sets. A positive value controls how many nodes must acknowledge the write instruction before the driver continues. A value of 1 would require the single server or primary (in a replica set) to acknowledge the write operation. A value of 3 would cause the driver to block until the write has been applied to the primary as well as two secondary servers (in a replica set).
A string value is used to control which tag sets are taken into account for write concerns. "majority" is special and ensures that the write operation has been applied to the majority (more than 50%) of the participating nodes.
"wTimeout"
This option is used in combination with the "w" option. It controls how many milliseconds the server waits for the write concern to be satisfied. If it takes longer then the server signals to the driver that it took too long and the driver will throw a MongoCursorException exception.
Returns a new database connection object.
Throws MongoConnectionException if it tries and fails to connect to the database for all hostnames given. It will also throw a MongoConnnectionException if an invalid username or password is given. See MongoConnectionException documentation for common exceptions and their causes.
| Version | Description |
|---|---|
| 1.3.0 |
Added the "readPreference", "readPreferenceTags", "w" and "wTimeout" options. |
| 1.2.0 |
Added the "username" and "password" options. Removed the "persist" option, as all connections are now persistent. It can still be used, but it doesn't affect anything.
The "replicaSet" option now takes a string, not a boolean. |
| 1.0.9 | Added the "replicaSet" option. |
| 1.0.2 |
Changed constructor to take an array of options. Pre-1.0.2, the constructor took the following parameters:
|
Example #1 MongoClient::__construct() replica set example
This example shows how to connect the driver to a replica set. It assumes that there is a set of three servers: sf1.example.com, sf2.example.com, and ny1.example.com. The primary could be any one of these servers.
<?php
// pass a comma-separated list of server names to the constructor
$m1 = new MongoClient("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet"));
// you only need to pass a single seed, the driver will derive the full list and
// find the primary from this seed
$m2 = new MongoClient("mongodb://ny1.example.com", array("replicaSet" => "myReplSet"));
?>
If the current primary fails, the driver will figure out which secondary server became the new primary and automatically start using that connection. Automatic failover will not work correctly if replicaSet is not specified.
At least one seed in the seed list must be up for the driver to connect to the replica set.
If you include seeds from two separate replica sets, behavior is undefined.
See the » core documentation on replica sets for more information.
Example #2 Connecting to a domain socket
In version 1.0.9+, you can use a UNIX domain socket to connect to an instance of MongoDB running locally. This should be slightly faster than using a network connection.
In version 1.5.0, the MongoDB server automatically opens a socket at /tmp/mongodb-<port>.sock. You can connect to this by specifying the path in your connection string:
<?php
// MongoDB server running locally on port 20000
$m = new MongoClient("mongodb:///tmp/mongodb-20000.sock");
?>
You can combine this with any other connections you'd like:
<?php
// try to connect to the domain socket, fall back to localhost connection
$m = new MongoClient("mongodb:///tmp/mongodb-27017.sock,localhost:27017");
?>
Example #3 MongoClient::__construct() authentication example
A user must exist in the admin database before attempting to use authentication. You can create one with the Mongo shell by running:
> use admin
switched to db admin
> db.addUser("testUser", "testPass");
{
"_id" : ObjectId("4b21272fd9ab21611d19095c"),
"user" : "testUser",
"pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59"
}
>
After creating a user with, in this case, username "testUser" and password "testPass", you can create an authenticated connection:
<?php
$m = new MongoClient("mongodb://testUser:testPass@localhost");
?>
Example #4 MongoClient::__construct() read preference example
<?php
// Prefer the nearest server in the "east" data center
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
See the read preferences section of this manual for further information.