Connecting to MongoDB can be as easy as new Mongo, but there are many additional options and configurations. The Mongo::__construct() page covers all of the API options, but this page gives some more practical use cases.
If MongoDB is started with the --auth option, connections must be authenticated before they are used. You can do this on a per-database level with MongoDB::authenticate():
<?php
$m = new Mongo();
$db = $m->admin;
$db->authenticate($username, $password);
?>
There is a major disadvantage to this method: if the database connection is dropped and then autoreconnects, the connection will no longer be authenticated.
If you use the connection string format described by Mongo::__construct(), the database will authenticate the connection as soon as it connects and reauthenticate if the connection is re-esetablished.
This is equivalent to the code above, except that reconnections to the database will automatically be authenticated:
<?php
$m = new Mongo("mongodb://${username}:${password}@localhost");
?>
By default, the driver will authenticate the user against the admin database. To authenticate with a different database, specify the database name after the hosts. This example will log the user into the "blog" database:
<?php
$m = new Mongo("mongodb://${username}:${password}@localhost/blog");
?>
To connect to a replica pair, specify both sides of the pair.
<?php
$m = new Mongo("mongodb://localhost:27017,localhost:27018");
?>
Order is irrelevant, the PHP driver will query the database servers to figure out which one is master. So long as one of them is up and master, the connection will succeed. If neither is up or there is no master, a MongoConnectionException will be thrown.
If the master becomes unavailable, the slave will not become master for a few seconds. During that time, the driver will not be able to perform any database operations because the master database is gone and the other database is a slave. Thus, if you attempt to do any sort of query (including "safe" operations) they will throw exceptions.
The slave will eventually realize that the master is gone and become master itself. At this point, the driver will make this its primary database connection and continue operating normally.
For more information on replica pairs, see the » core documentation.
Creating new connection to the database is very slow. To minimize the number of connections that you need to make, you can use persistent connections. A persistent connection is saved by PHP, so you can use the same connection for multiple requests.
For example, this simple program connects to the database 1000 times:
<?php
for ($i=0; $i<1000; $i++) {
$m = new Mongo();
}
?>
It takes approximately 18 seconds to execute. If we change it to use a persistent connection:
<?php
for ($i=0; $i<1000; $i++) {
$m = new Mongo("localhost:27017", array("persist" => "x"));
}
?>
...it takes less than .02 seconds to execute, as it only makes one database connection.
Persistent connections need an identifier string (which is "x" in the above example) to uniquely identify them. For a persistent connection to be used, the hostname, port, persist string, and username and password (if given) must match an existing persistent connection. Otherwise, a new connection will be created with this identifying information.
If you are running MongoDB locally and have version 1.0.9 or better of the driver, you can connect to the database via file. MongoDB automatically opens a socket file on startup: /tmp/mongodb-<port>.sock (C:\tmp\mongodb-<27017>.sock on Windows).
To connect to the socket file, specify the path in your MongoDB connection string:
<?php
$m = new Mongo("mongodb:///tmp/mongo-27017.sock");
?>
If you would like to use authentication on connection (as described above) with a socket file, you must specify a port of 0 so that the connection string parser knows where the end of the connection string is.
<?php
$m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
?>