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 details and advice for practical use cases.
If MongoDB is started with the --auth or --keyFile options, you must log in before you can do any operations with the driver. You can log in on connection by supplying the username and password in the connection URI:
<?php
$m = new Mongo("mongodb://${username}:${password}@localhost");
?>
If your connection is dropped, the driver will automatically attempt to reconnect and reauthenticate you.
You can also authenticate 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 connection is dropped and then reconnects, the new connection will not be authenticated. If you use the URI format, the PHP driver will automatically authenticate the user whenever a new connection is made.
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 set, specify one or more members of the set and use the replicaSet option.
<?php
$m = new Mongo("mongodb://localhost:27017", array("replicaSet" => "myReplSetName"));
?>
Version 1.0.9+ of the driver is required to connect to a replica set (earlier versions of the driver will not autodetect the master or reconnect correctly).
The PHP driver will query the database server(s) listed to figure out who is master. So long as it can connect to at least one host listed and find a master, the connection will succeed. If it cannot make a connection to any servers listed or cannot find a master, a MongoConnectionException will be thrown.
If the master becomes unavailable, the slaves will not promote a new master for a few seconds. During that time, this connection will not be able to perform any database operations (connections to slaves will still be able to perform reads). Thus, if you attempt to do any sort of read or write on this connection, it will throw an exception.
Once a master is elected, attempting to perform a read or write will allow the driver to detect the new master. The driver will make this its primary database connection and continue operating normally.
For more information on replica sets, see the » core documentation.
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.
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");
?>
Creating connections is one of the most heavyweight things that the driver does. It can take hundreds of milliseconds to set up a connection correctly, even on a fast network. Thus, the driver tries to minimize the number of new connections created by reusing connections from a pool.
When a user creates a new instance of Mongo, all necessary connections will be taken from their pools (replica sets may require multple connections, one for each member of the set). When the Mongo instance goes out of scope, the connections will be returned to the pool. When the PHP process exits, all connections in the pools will be closed.
Connection pools can generate a large number of connections. This is expected and, using a little arithmetic, you can figure out how many connections to expect. There are three factors in the total number of connections:
connections_per_pool
Each connection pool will create, by default, an unlimited number of connections. One might assume that this is a problem: if it can create an unlimited number of connections, couldn't it create thousands and the server would run out of file descriptors? In practice, this is unlikely, as unused connections are returned to the pool to be used later, so future connections will use the same connection instead of creating a new one. Unless you create thousands of connections at once without letting any go out of scope, the number of connections open should stay at a reasonable number.
You can see how many connections you have in a pool using the MongoPool::info() function. Add up the "in use" and "in pool" fields for a given server. That is the total number of connections for that pool.
pools_per_process
Each MongoDB server address you're connecting to gets its own connection pool. For example, if your local hostname is "example.net", connecting to "example.net:27017", "localhost:27017", and "/tmp/mongodb-27017.sock" will create three connection pools. You can see how many connection pools you have open using MongoPool::info().
processes
Each PHP process has a separate set of pools. PHP-FPM and Apache generally create between 6 and a couple dozen PHP worker children. Check your settings to see what the max number of PHP processes is that can be spawned.
If you are using PHP-FPM, estimating the number of connections can be tricky because it will spawn more PHP-FPM workers under heavy load. To be on the safe side, look at the max_children parameter or add up spare_servers+start_servers (choose whichever number is higher). That's how many PHP processes (and, thus sets of pools) you should plan for.
The three variables above can be multiplied together to give the max number of connections expected: connections_per_pool*pools_per_process*processes. Note that connections_per_pool can be different for different pools, so connections_per_pool should be the max.
For example, suppose we're getting 30 connections per pool, 10 pools per PHP process, and 128 PHP processes. Then we can expect 38400 connections from this machine. Thus, we should set this machine's file descriptor limit to be high enough to handle all of these connections or it may run out of file descriptors.
See MongoPool for more information on connection pooling.
Note:
This section is not relevant for 1.2.0+. In 1.2.0+, connections are always persistent and managed automatically by the driver. See MongoPool for more information on pooling.
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.
Persistent connections are highly recommended and should always be used in production unless there is a compelling reason not to. Most of the reasons that they are not recommended for relational databases are irrelevant to MongoDB.