<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Creates a new database connection object</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongoclient.connect.html">MongoClient::connect</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongoclient.dropdb.html">MongoClient::dropDB</a></div>
<div class="up"><a href="class.mongoclient.html">MongoClient</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongoclient.construct" class="refentry">
<div class="refnamediv">
<h1 class="refname">MongoClient::__construct</h1>
<p class="verinfo">(PECL mongoclient >=0.9.0)</p><p class="refpurpose"><span class="refname">MongoClient::__construct</span> — <span class="dc-title">Creates a new database connection object</span></p>
</div>
<div class="refsect1 description" id="refsect1-mongoclient.construct-description">
<h3 class="title">Description</h3>
<div class="constructorsynopsis dc-description">
<span class="modifier">public</span> <span class="methodname"><strong>MongoClient::__construct()</strong></span>
([ <span class="methodparam"><span class="type">string</span> <code class="parameter">$server</code><span class="initializer"> = "mongodb://localhost:27017"</span></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$options</code><span class="initializer"> = array("connect" => <strong><code>TRUE</code></strong>)</span></span>
]] )</div>
<p class="para rdfs-comment">
If no parameters are passed, this connects to "localhost:27017" (or whatever
was specified in php.ini for
<a href="mongo.configuration.html#ini.mongo.default-host" class="link">mongo.default_host</a> and
<a href="mongo.configuration.html#ini.mongo.default-port" class="link">mongo.default_port</a>).
</p>
<p class="para">
<em><code class="parameter">server</code></em> should have the form:
<div class="example-contents">
<div class="cdata"><pre>
mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
</pre></div>
</div>
</p>
<p class="para">
The connection string always starts with <em>mongodb://</em>, to
indicate it is a connection string in this form.
</p>
<p class="para">If <em>username</em> and <em>password</em>
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 <em>@</em>, if specified.
</p>
<p class="para">
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 <a href="class.mongoconnectionexception.html" class="classname">MongoConnectionException</a>. Please see the
<a href="mongo.connecting.rs.html" class="link">Replica Sets</a> section for
information on how to connect to Replica Sets.
</p>
<p class="para">
If you specified a username and password, you may specify a database to
authenticate with. If <em>db</em> is not specified, "admin" will
be used.
</p>
<p class="para">
An optional query string may be used to specify extra options. The same
options are supported through the <em><code class="parameter">options</code></em> array as
well, and are therefore redescribed there. See the <a href="" class="link">examples below</a> on
how to set those options.
</p>
<p class="para">
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 <a href="mongo.readpreferences.html" class="link">read preferences</a> documentation page.
</p>
</div>
<div class="refsect1 parameters" id="mongo.mongoclient.construct.parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term">
<em><code class="parameter">server</code></em>
</span>
<dd>
<p class="para">
The server name.
</p>
</dd>
</dt>
<dt>
<span class="term">
<em><code class="parameter">options</code></em>
</span>
<dd>
<p class="para">
An array of options for the connection. Currently available options
include:
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
<em>"connect"</em>
</p>
<p class="para">
If the constructor should connect before returning. Default is
<strong><code>TRUE</code></strong>. When set to <strong><code>FALSE</code></strong> the driver will
<em class="emphasis">automatically</em> connect to the server whenever
it is necessary to do a query. Alternatively, you can run
<span class="function"><a href="mongoclient.connect.html" class="function">MongoClient::connect()</a></span> manually.
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
This option is not supported through the connection string.
</p>
</div>
</li>
<li class="listitem">
<p class="para">
<em>"connectTimeoutMS"</em>
</p>
<p class="para">
How long a connection can take to be opened before timing out in
milliseconds.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"db"</em>
</p>
<p class="para">
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.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"fsync"</em>
</p>
<p class="para">
When <em>fsync</em> is set, all write operations on the
database will only return when the write has been synched to disk.
This makes write operations a lot slower,
but it guarantees that the write operation has succeeded and
committed to disk. If you have journalling enabled in MongoDB (the
default) then the sync happens only to the
<em class="emphasis">journal</em>. If journalling is not enabled, then
using <em>fsync</em> requires a full flush to disk.
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
Please <em class="emphasis">do not use</em> this option as it is
deprecated, but use <em>journal</em> option instead,
perhaps in combination with the <em>w</em> option.
</p>
</div>
</li>
<li class="listitem">
<p class="para">
<em>"journal"</em>
</p>
<p class="para">
When <em>journal</em> is set, all write operations on the
database will block until the database server has flushed the
journal to disk. This makes the write operations marginally slower,
but it guarantees that the write operation has succeeded and the
operation can be recovered in case of total system failure.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"password"</em>
</p>
<p class="para">
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.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"readPreference"</em>
</p>
<p class="para">
Specifies the read preference type. Read preferences provide you
with control from which secondaries data can be read from.
</p>
<p class="para">
Allowed values are: <strong><code>MongoClient::RP_PRIMARY</code></strong>,
<strong><code>MongoClient::RP_PRIMARY_PREFERRED</code></strong>,
<strong><code>MongoClient::RP_SECONDARY</code></strong>,
<strong><code>MongoClient::RP_SECONDARY_PREFERRED</code></strong> and
<strong><code>MongoClient::RP_NEAREST</code></strong>.
</p>
<p class="para">
See the documentation on <a href="mongo.readpreferences.html" class="link">read
preferences</a> for more information.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"readPreferenceTags"</em>
</p>
<p class="para">
Specifies the read preference tags as an array of strings. Tags can be
used in combination with the <em>readPreference</em> option
to further control which secondaries data might be read from.
</p>
<p class="para">
See the documentation on <a href="mongo.readpreferences.html" class="link">read
preferences</a> for more information.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"replicaSet"</em>
</p>
<p class="para">
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.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"socketTimeoutMS"</em>
</p>
<p class="para">
How long a send or receive on a socket can take before timing out.
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">
This is a client side timeout. If an <em>insert</em> hits
the <em>"socketTimeoutMS"</em> value there is no way to
know if the server actually received the write or not.
</span>
</p></blockquote>
</p>
</li>
<li class="listitem">
<p class="para">
<em>"ssl"</em>
</p>
<p class="para">
A boolean to specify whether you want to enable SSL for the
connections to MongoDB. Extra options such as certificates
can be set with <a href="context.ssl.html" class="xref">SSL context options</a>.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"username"</em>
</p>
<p class="para">
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.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"w"</em>
</p>
<p class="para">
The <em>w</em> option specifies the
<a href="mongo.writeconcerns.html" class="link">Write Concern</a> for the driver,
which determines how long the driver blocks when writing. The
default value is <em>1</em>.
</p>
<p class="para">
This option is applicable when connecting to both single servers and
replica sets. A positive value controls how <em class="emphasis">many</em>
nodes must acknowledge the write instruction before the driver
continues. A value of <em>1</em> would require the single
server or primary (in a replica set) to acknowledge the write
operation. A value of <em>3</em> 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).
</p>
<p class="para">
A string value is used to control which tag sets are taken into
account for write concerns. <em>"majority"</em> is special
and ensures that the write operation has been applied to the majority
(more than 50%) of the participating nodes.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"wTimeoutMS"</em>
</p>
<p class="para">
This option is used in combination with the <em>"w"</em>
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 <a href="class.mongocursorexception.html" class="classname">MongoCursorException</a> exception.
</p>
</li>
</ul>
</p>
<p class="para">
The following options are deprecated and should no longer be used:
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
<em>"timeout"</em>
</p>
<p class="para">
Deprecated alias for "connectTimeoutMS".
</p>
</li>
<li class="listitem">
<p class="para">
<em>"wTimeout"</em>
</p>
<p class="para">
Deprecated alias for "wTimeoutMS".
</p>
</li>
</ul>
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-mongoclient.construct-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns a new database connection object.
</p>
</div>
<div class="refsect1 errors" id="refsect1-mongoclient.construct-errors">
<h3 class="title">Errors/Exceptions</h3>
<p class="para">
Throws <a href="class.mongoconnectionexception.html" class="classname">MongoConnectionException</a> if it tries and fails
to connect to the database for all hostnames given. It will also throw a
<strong class="classname">MongoConnnectionException</strong> if an invalid username or
password is given. See <a href="class.mongoconnectionexception.html" class="classname">MongoConnectionException</a>
documentation for common exceptions and their causes.
</p>
</div>
<div class="refsect1 examples" id="mongo.mongoclient.construct.examples">
<h3 class="title">Examples</h3>
<div class="example" id="example-1397">
<p><strong>Example #1 <span class="function"><strong>MongoClient::__construct()</strong></span> replica set example</strong></p>
<div class="example-contents"><p>
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.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000">// pass a comma-separated list of server names to the constructor<br />// Note that we don't need to pass in all the members of the replicaset, the driver <br />// will derive the full list.<br /></span><span style="color: #0000BB">$m1 </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #DD0000">"mongodb://sf2.example.com,ny1.example.com"</span><span style="color: #007700">, array(</span><span style="color: #DD0000">"replicaSet" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"myReplSet"</span><span style="color: #007700">));<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
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 <em>replicaSet</em>
is not specified.
</p></div>
<div class="example-contents"><p>
At least one seed in the seed list must be up for the driver to connect to
the replica set.
</p></div>
<div class="example-contents"><p>
If you include seeds from two separate replica sets, behavior is undefined.
</p></div>
<div class="example-contents"><p>See the
<a href="http://docs.mongodb.org/manual/replication/" class="link external">» core documentation</a> on
replica sets for more information.
</p></div>
</div>
<div class="example" id="example-1398">
<p><strong>Example #2 Connecting to a domain socket</strong></p>
<div class="example-contents"><p>
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.
</p></div>
<div class="example-contents"><p>
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:
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000">// MongoDB server running locally on port 20000<br /></span><span style="color: #0000BB">$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #DD0000">"mongodb:///tmp/mongodb-20000.sock"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
You can combine this with any other connections you'd like:
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000">// try to connect to the domain socket, fall back to localhost connection<br /></span><span style="color: #0000BB">$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #DD0000">"mongodb:///tmp/mongodb-27017.sock,localhost:27017"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="example-1399">
<p><strong>Example #3 <span class="function"><strong>MongoClient::__construct()</strong></span> authentication example</strong></p>
<div class="example-contents"><p>
A user must exist in the admin database before attempting to use
authentication. You can create one with the Mongo shell by running:
</p></div>
<div class="example-contents">
<div class="cdata"><pre>
> use admin
switched to db admin
> db.addUser("testUser", "testPass");
{
"_id" : ObjectId("4b21272fd9ab21611d19095c"),
"user" : "testUser",
"pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59"
}
>
</pre></div>
</div>
<div class="example-contents"><p>
After creating a user with, in this case, username "testUser" and password
"testPass", you can create an authenticated connection:
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #DD0000">"mongodb://testUser:testPass@localhost"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="example-1400">
<p><strong>Example #4 <span class="function"><strong>MongoClient::__construct()</strong></span> read preference example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000">// Prefer the nearest server in the "east" data center<br /></span><span style="color: #0000BB">$uri </span><span style="color: #007700">= </span><span style="color: #DD0000">'mongodb://rs1.example.com,rs2.example.com/'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$uri </span><span style="color: #007700">.= </span><span style="color: #DD0000">'?readPreference=nearest'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$uri </span><span style="color: #007700">.= </span><span style="color: #DD0000">'&readPreferenceTags=dc:east'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #0000BB">$uri</span><span style="color: #007700">, array(</span><span style="color: #DD0000">'replicaSet' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'rs'</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
See the <a href="mongo.readpreferences.html" class="link">read preferences</a>
section of this manual for further information.
</p></div>
</div>
<div class="example" id="example-1401">
<p><strong>Example #5 <span class="function"><strong>MongoClient::__construct()</strong></span> options example</strong></p>
<div class="example-contents"><p>
Options can be passed both through the query string in the connection
string, or as an array passed as second argument to the constructor.
</p></div>
<div class="example-contents"><p>
Here we set the journal option to true and readPreference to secondary
preferred as default for all write operations:
</p></div>
<div class="example-contents">
<div class="cdata"><pre>
<?php
$m = new MongoClient("mongodb://localhost/?journal=true&readPreference=secondary");
?>
</pre></div>
</div>
<div class="example-contents"><p>
And now we do the same, but as an options array:
</p></div>
<div class="example-contents">
<div class="cdata"><pre>
<?php
$options = array(
'journal' => true,
'readPreference' => 'secondary',
);
$m = new MongoClient("mongodb://localhost/", $options);
?>
</pre></div>
</div>
</div>
<div class="example" id="example-1402">
<p><strong>Example #6 <span class="function"><strong>MongoClient::__construct()</strong></span> read preference example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000">// Prefer the nearest server in the "east" data center<br /></span><span style="color: #0000BB">$uri </span><span style="color: #007700">= </span><span style="color: #DD0000">'mongodb://rs1.example.com,rs2.example.com/'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$uri </span><span style="color: #007700">.= </span><span style="color: #DD0000">'?readPreference=nearest'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$uri </span><span style="color: #007700">.= </span><span style="color: #DD0000">'&readPreferenceTags=dc:east'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">(</span><span style="color: #0000BB">$uri</span><span style="color: #007700">, array(</span><span style="color: #DD0000">'replicaSet' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'rs'</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
See the <a href="mongo.readpreferences.html" class="link">read preferences</a>
section of this manual for further information.
</p></div>
</div>
</div>
<div class="refsect1 changelog" id="refsect1-mongoclient.construct-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>1.4.0</td>
<td>
<p class="para">
Added the <em>"wTimeoutMS"</em> option has replacement
for <em>"wTimeout"</em>.
</p>
</td>
</tr>
<tr>
<td>1.3.4</td>
<td>
<p class="para">
Added the <em>"connectTimeoutMS"</em> and
<em>"socketTimeoutMS"</em> options.
</p>
</td>
</tr>
<tr>
<td>1.3.0</td>
<td>
<p class="para">
Added the <em>"readPreference"</em>,
<em>"readPreferenceTags"</em>, <em>"w"</em> and
<em>"wTimeout"</em> options.
</p>
</td>
</tr>
<tr>
<td>1.2.0</td>
<td>
<p class="para">
Added the <em>"username"</em> and
<em>"password"</em> options.
</p>
<p class="para">
Removed the <em>"persist"</em> option, as all connections are
now persistent. It can still be used, but it doesn't affect anything.
</p>
<dl>
<dt>
<span class="term">
<em><code class="parameter">"persist"</code></em>
</span>
<dd>
<p class="para">
If the connection should be persistent. If set, the connection will
be persistent. The string representation of the value is used as an
ID for the connection, so two instances of
<a href="class.mongoclient.html" class="classname">MongoClient</a> that are initialized with
<em>array("persist" => "foobar")</em> will share the same
database connection, whereas an instance initialized with
<em>array("persist" => "barbaz")</em> will use a different
database connection.
</p>
</dd>
</dt>
</dl>
<p class="para">
The <em>"replicaSet"</em> option now takes a string, not a
boolean.
</p>
</td>
</tr>
<tr>
<td>1.0.9</td>
<td>Added the <em>"replicaSet"</em> option.</td>
</tr>
<tr>
<td>1.0.2</td>
<td>
<p class="para">
Changed constructor to take an array of options. Pre-1.0.2, the
constructor took the following parameters:
</p>
<dl>
<dt>
<span class="term">
<em><code class="parameter">server</code></em>
</span>
<dd>
<p class="para">
The server name.
</p>
</dd>
</dt>
<dt>
<span class="term">
<em><code class="parameter">connect</code></em>
</span>
<dd>
<p class="para">
Optional boolean parameter specifying if the constructor should
connect to the database before returning. Defaults to <strong><code>TRUE</code></strong>.
</p>
</dd>
</dt>
<dt>
<span class="term">
<em><code class="parameter">persistent</code></em>
</span>
<dd>
<p class="para">
If the connection should be persistent.
</p>
</dd>
</dt>
<dt>
<span class="term">
<em><code class="parameter">paired</code></em>
</span>
<dd>
<p class="para">
If the connection should be paired.
</p>
</dd>
</dt>
</dl>
</td>
</tr>
</tbody>
</table>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongoclient.connect.html">MongoClient::connect</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongoclient.dropdb.html">MongoClient::dropDB</a></div>
<div class="up"><a href="class.mongoclient.html">MongoClient</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
