php-doc-en/reference/mongo/connecting.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<section xml:id="mongo.connecting" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Connecting</title>

 <para>
  Connecting to MongoDB can be as easy as <literal>new Mongo</literal>, but 
  there are many additional options and configurations. The 
  <function>Mongo::__construct</function> page covers all of the API options,
  but this page gives some more practical use cases.
 </para>

 <section>
  <title>Logging In on Connection</title>
  <para>
   If MongoDB is started with the <literal>--auth</literal> option, connections
   must be authenticated before they are used.  You can do this on a 
   per-database level with <function>MongoDB::authenticate</function>:
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$m = new Mongo();
$db = $m->admin;

$db->authenticate($username, $password);

?>
]]>
  </programlisting>
  <para>
   There is a major disadvantage to this method: if the database connection is
   dropped and then autoreconnects, the connection will no longer be 
   authenticated.
  </para>
  <para>
   If you use the connection string format described by 
   <function>Mongo::__construct</function>, the database will authenticate the
   connection as soon as it connects and reauthenticate if the connection is 
   re-esetablished.
  </para>
  <para>
   This is equivalent to the code above, except that reconnections to the 
   database will automatically be authenticated:
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$m = new Mongo("mongodb://${username}:${password}@localhost");

?>
]]>
  </programlisting>
  <para>
   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:
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$m = new Mongo("mongodb://${username}:${password}@localhost/blog");

?>
]]>
  </programlisting>
 </section>

 <section>
  <title>Replica Pairs</title>
  <para>
   To connect to a replica pair, specify both sides of the pair.
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$m = new Mongo("mongodb://localhost:27017,localhost:27018");

?>
]]>
  </programlisting>
  <para>
   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 
   <classname>MongoConnectionException</classname> will be thrown.
  </para>
  <para>
   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.
  </para>
  <para>
   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.
  </para>
  <para>
   For more information on replica pairs, see the 
   <link xlink:href="&url.mongodb.replica;">core documentation</link>.
  </para>
 </section>

 <section>
  <title>Persistent Connections</title>

  <para>
   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.
  </para>

  <para>
   For example, this simple program connects to the database 1000 times:
  </para>

  <programlisting role="php">
<![CDATA[
<?php

for ($i=0; $i<1000; $i++) {
  $m = new Mongo();
}

?>
]]>
  </programlisting>

  <para>
   It takes approximately 18 seconds to execute.  If we change it to use a 
   persistent connection:
  </para>

  <programlisting role="php">
<![CDATA[
<?php

for ($i=0; $i<1000; $i++) {
  $m = new Mongo("localhost:27017", array("persist" => "x"));
}

?>
]]>
  </programlisting>

  <para>
   ...it takes less than .02 seconds to execute, as it only makes one database
   connection.
  </para>

  <para>
   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.
  </para>
 </section>

</section>