sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Revise replica set language and MongoClient references

Browse source 
Replace master/slave terminology with primary/secondary
Change most Mongo class references to MongoClient
Enforce 80-char line widths and trim trailing whitespace
Add literal formatting within some paragraphs

https://jira.mongodb.org/browse/PHP-583


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328496 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Jeremy Mikola 2012-11-26 03:07:28 +00:00
parent f8f64b7216
commit 8a4640c71c
52 changed files with 345 additions and 332 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

149
reference/mongo/connecting.xml
View file

@ -5,10 +5,11 @@
<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 details and advice for practical use cases.
Connecting to MongoDB can be as easy as <literal>new MongoClient</literal>,
but there are many additional options and configurations. The documentation
for <function>MongoClient::__construct</function> covers all of the API
options, but this page gives some more details and advice for practical use
cases.
</para>
<section>
@ -19,16 +20,16 @@
any operations with the driver. You may authenticate a connection by
specifying the username and password in either the connection URI or the
<literal>"username"</literal> and <literal>"password"</literal> options for
<function>Mongo::__construct</function>.
<function>MongoClient::__construct</function>.
</para>
<programlisting role="php">
<![CDATA[
<?php
// Specifying the username and password in the connection URI (preferred)
$m = new Mongo("mongodb://${username}:${password}@localhost");
$m = new MongoClient("mongodb://${username}:${password}@localhost");
// Specifying the username and password via the options array (alternative)
$m = new Mongo("mongodb://localhost", array("username" => $username, "password" => $password));
$m = new MongoClient("mongodb://localhost", array("username" => $username, "password" => $password));
?>
]]>
</programlisting>
@ -36,16 +37,16 @@ $m = new Mongo("mongodb://localhost", array("username" => $username, "password"
By default, the driver will authenticate against the <literal>admin</literal>
database. You may authenticate against a different database by specifying it
in either the connection URI or the <literal>"db"</literal> option for
<function>Mongo::__construct</function>.
<function>MongoClient::__construct</function>.
</para>
<programlisting role="php">
<![CDATA[
<?php
// Specifying the authentication database in the connection URI (preferred)
$m = new Mongo("mongodb://${username}:${password}@localhost/myDatabase");
$m = new MongoClient("mongodb://${username}:${password}@localhost/myDatabase");
// Specifying the authentication database via the options array (alternative)
$m = new Mongo("mongodb://${username}:${password}@localhost", array("db" => "myDatabase"));
$m = new MongoClient("mongodb://${username}:${password}@localhost", array("db" => "myDatabase"));
?>
]]>
</programlisting>
@ -59,45 +60,47 @@ $m = new Mongo("mongodb://${username}:${password}@localhost", array("db" => "myD
<title>Replica Sets</title>
<para>
To connect to a replica set, specify one or more members of the set and use
the <literal>replicaSet</literal> option. Multiple servers may be delimited
the <literal>"replicaSet"</literal> option. Multiple servers may be delimited
by a comma.
</para>
<programlisting role="php">
<![CDATA[
<?php
// Using multiple servers as the seed list (prefered)
$m = new Mongo("mongodb://rs1.example.com:27017,rs2.example.com:27017/?replicaSet=myReplSetName"));
$m = new MongoClient("mongodb://rs1.example.com:27017,rs2.example.com:27017/?replicaSet=myReplSetName"));
// Using one server as the seed list
$m = new Mongo("mongodb://rs1.example.com:27017", array("replicaSet" => "myReplSetName"));
$m = new MongoClient("mongodb://rs1.example.com:27017", array("replicaSet" => "myReplSetName"));
// Using multiple servers as the seed list
$m = new Mongo("mongodb://rs1.example.com:27017,rs2.example.com:27017", array("replicaSet" => "myReplSetName"));
$m = new MongoClient("mongodb://rs1.example.com:27017,rs2.example.com:27017", array("replicaSet" => "myReplSetName"));
?>
]]>
</programlisting>
<para>
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).
Version 1.0.9+ of the driver is required to connect to a replica set. Earlier
versions of the driver will not auto-detect the primary or reconnect
correctly.
</para>
<para>
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
The PHP driver will query the database server(s) listed to determine the
primary. So long as it can connect to at least one host listed and find a
primary, the connection will succeed. If it cannot make a connection to any
servers listed or cannot find a primary, a
<classname>MongoConnectionException</classname> will be thrown.
</para>
<para>
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.
If the primary becomes unavailable, an election will take place and a
secondary will be promoted to the role of primary (unless a majority vote
cannot be established). During this time
(<link xlink:href="&url.mongodb.replica.failover;">20-60 seconds</link>), the
connection will not be able to perform any write operations and attempts to
do so will result in an exception. Connections to secondaries will still be
able to perform reads.
</para>
<para>
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
Once a primary is elected, attempting to perform a read or write will allow
the driver to detect the new primary. The driver will make this its primary
database connection and continue operating normally.
</para>
<para>
@ -118,10 +121,10 @@ $m = new Mongo("mongodb://rs1.example.com:27017,rs2.example.com:27017", array("r
<?php
// Using one server as the seed list
$m = new Mongo("mongodb://mongos1.example.com:27017");
$m = new MongoClient("mongodb://mongos1.example.com:27017");
// Using multiple servers as the seed list
$m = new Mongo("mongodb://mongos1.example.com:27017,mongos2.example.com:27017"));
$m = new MongoClient("mongodb://mongos1.example.com:27017,mongos2.example.com:27017"));
?>
]]>
@ -142,8 +145,8 @@ $m = new Mongo("mongodb://mongos1.example.com:27017,mongos2.example.com:27017"))
<para>
If you are running MongoDB locally and using version 1.0.9+ of the driver,
you can connect to the database via file. MongoDB automatically opens a
socket file on startup: <literal>/tmp/mongodb-&lt;port&gt;.sock.</literal>
you can connect to the database via a socket file. MongoDB automatically
opens a socket file on startup: <literal>/tmp/mongodb-&lt;port&gt;.sock.</literal>
</para>
<para>
@ -154,21 +157,22 @@ $m = new Mongo("mongodb://mongos1.example.com:27017,mongos2.example.com:27017"))
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo("mongodb:///tmp/mongo-27017.sock");
$m = new MongoClient("mongodb:///tmp/mongo-27017.sock");
?>
]]>
</programlisting>
<para>
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.
If you would like to authenticate against a database (as described above)
with a socket file, you must specify a port of <literal>0</literal> so that
the connection string parser can detect the end of the socket path.
Alternatively, you can use the constructor options.
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
$m = new MongoClient("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
?>
]]>
</programlisting>
@ -180,23 +184,24 @@ $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
<para>
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
even on a fast network. Thus, the driver tries to minimize the number of new
connections created by reusing connections from a pool.
</para>
<para>
When a user creates a new instance of <classname>Mongo</classname>, all
When a user creates a new instance of <classname>MongoClient</classname>, all
necessary connections will be taken from their pools (replica sets may
require multple connections, one for each member of the set). When the
<classname>Mongo</classname> 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.
require multiple connections, one for each member of the set). When the
<classname>MongoClient</classname> 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.
</para>
<section>
<title>"Why do I have so many open connections?"</title>
<para>
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:
Connection pools can generate a large number of connections. This is
expected and, using a little arithmetic, you can figure out how many
connections will be created. There are three factors in determining the
total number of connections:
</para>
<itemizedlist>
<listitem>
@ -218,8 +223,8 @@ $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
</para>
<para>
You can see how many connections you have in a pool using the
<function>MongoPool::info</function> function. Add up the "in use" and
"in pool" fields for a given server. That is the total number of
<function>MongoPool::info</function> function. Add up the "in use" and
"in pool" fields for a given server. That is the total number of
connections for that pool.
</para>
</listitem>
@ -231,9 +236,9 @@ $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
</para>
<para>
Each MongoDB server address you're connecting to gets its own connection
pool. For example, if your local hostname is "example.net", connecting
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
will create three connection pools. You can see how many connection pools
you have open using <function>MongoPool::info</function>.
</para>
</listitem>
@ -244,31 +249,34 @@ $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
</literal>
</para>
<para>
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.
Each PHP process has a separate set of pools. PHP-FPM and Apache
generally create between 6 and a couple of dozen PHP worker children.
Check your settings to see what the max number of PHP processes is that
can be spawned.
</para>
<para>
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.
on the safe side, look at the <literal>max_children</literal> parameter or
add up <literal>spare_servers</literal> + <literal>start_servers</literal>
(choose whichever number is higher). That will indicate how many PHP
processes (i.e. sets of pools) you should plan for.
</para>
</listitem>
</itemizedlist>
<para>
The three variables above can be multiplied together to give the max
number of connections expected:
<literal>connections_per_pool*pools_per_process*processes</literal>. Note
that <literal>connections_per_pool</literal> can be different for different
<literal>connections_per_pool</literal> *
<literal>pools_per_process</literal> *
<literal>processes</literal>. Note that
<literal>connections_per_pool</literal> can be different for different
pools, so <literal>connections_per_pool</literal> should be the max.
</para>
<para>
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
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.
</para>
@ -291,8 +299,8 @@ $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
</note>
<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
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>
@ -306,7 +314,7 @@ $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
<?php
for ($i=0; $i<1000; $i++) {
$m = new Mongo();
$m = new MongoClient();
}
?>
@ -314,7 +322,7 @@ for ($i=0; $i<1000; $i++) {
</programlisting>
<para>
It takes approximately 18 seconds to execute. If we change it to use a
It takes approximately 18 seconds to execute. If we change it to use a
persistent connection:
</para>
@ -323,7 +331,7 @@ for ($i=0; $i<1000; $i++) {
<?php
for ($i=0; $i<1000; $i++) {
$m = new Mongo("localhost:27017", array("persist" => "x"));
$m = new MongoClient("localhost:27017", array("persist" => "x"));
}
?>
@ -337,10 +345,11 @@ for ($i=0; $i<1000; $i++) {
<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.
example) to uniquely identify them. For a persistent connection to be used,
the hostname, port, persist string, and authentication credentials (username,
password and database, if given) must match an existing persistent
connection. Otherwise, a new connection will be created with this identifying
information.
</para>
<para>
Persistent connections are <emphasis>highly recommended</emphasis> and should

19
reference/mongo/mongo/getslave.xml
View file

@ -15,22 +15,23 @@
</methodsynopsis>
<para>
This finds the address of the slave currently being used for reads. It is a
read-only method: it does not change anything about the internal state of the
object.
This finds the address of the secondary currently being used for reads. It is
a read-only method: it does not change anything about the internal state of
the object.
</para>
<para>
When you create a connection to the database, the driver will not immediately
decide on a slave to use. Thus, after you connect, this function will return
&null; even if there are slaves available. When you first do a query with
slaveOkay set, at that point the driver will choose a slave for this
connection. At that point, this function will return the chosen slave.
decide on a secondary to use. Thus, after you connect, this function will
return &null; even if there are secondaries available. When you first do a
query with slaveOkay set, at that point the driver will choose a secondary
for this connection. At that point, this function will return the chosen
secondary.
</para>
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to slaves.
information on distributing reads to secondaries.
</para>
</refsect1>
@ -43,7 +44,7 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The address of the slave this connection is using for reads.
The address of the secondary this connection is using for reads.
</para>
<para>
This returns &null; if this is not connected to a replica set or not yet

2
reference/mongo/mongo/getslaveokay.xml
View file

@ -16,7 +16,7 @@
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to slaves.
information on distributing reads to secondaries.
</para>
</refsect1>

8
reference/mongo/mongo/pooldebug.xml
View file

@ -44,7 +44,7 @@
<listitem>
<para>
The number of connections currently being used by
<classname>Mongo</classname> instances.
<classname>MongoClient</classname> instances.
</para>
</listitem>
</varlistentry>
@ -67,9 +67,9 @@
The number of connections that could be created by this pool. For
example, suppose a pool had 5 connections remaining and 3 connections in
the pool. We could create 8 new instances of
<classname>Mongo</classname> before we exhausted this pool (assuming no
instances of <classname>Mongo</classname> went out of scope, returning
their connections to the pool).
<classname>MongoClient</classname> before we exhausted this pool
(assuming no instances of <classname>MongoClient</classname> went out of
scope, returning their connections to the pool).
</para>
<para>
A negative number means that this pool will spawn unlimited connections.

6
reference/mongo/mongo/setslaveokay.xml
View file

@ -16,7 +16,7 @@
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to slaves.
information on distributing reads to secondaries.
</para>
</refsect1>
@ -30,8 +30,8 @@
</term>
<listitem>
<para>
If reads should be sent to secondary members of a replica set for all
possible queries using this <classname>Mongo</classname> instance.
If reads should be sent to secondary members of a replica set for all
possible queries using this <classname>MongoClient</classname> instance.
</para>
</listitem>
</varlistentry>

25
reference/mongo/mongo/switchslave.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="mongo.switchslave" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::switchSlave</refname>
<refpurpose>Choose a new slave for slaveOkay reads</refpurpose>
<refpurpose>Choose a new secondary for slaveOkay reads</refpurpose>
</refnamediv>
<refsect1 role="description">
@ -15,15 +15,15 @@
</methodsynopsis>
<para>
This choses a random slave for a connection to read from. It is called
automatically by the driver and should not need to be used. It calls
<function>Mongo::getHosts</function> (to refresh the status of hosts) and
<function>Mongo::getSlave</function> (to get the return value).
This choses a random secondary for a connection to read from. It is called
automatically by the driver and should not need to be used. It calls
<function>MongoClient::getHosts</function> (to refresh the status of hosts)
and <function>Mongo::getSlave</function> (to get the return value).
</para>
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to slaves.
information on distributing reads to secondaries.
</para>
</refsect1>
@ -36,14 +36,15 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The address of the slave this connection is using for reads. This may be the
same as the previous address as addresses are randomly chosen. It may return
only one address if only one secondary (or only the primary) is available.
The address of the secondary this connection is using for reads. This may be
the same as the previous address as addresses are randomly chosen. It may
return only one address if only one secondary (or only the primary) is
available.
</para>
<para>
For example, if we had a three member replica set with a primary, secondary,
and arbiter this method would always return the address of the secondary.
If the secondary became unavailable, this method would always return the
For example, if we had a three member replica set with a primary, secondary,
and arbiter this method would always return the address of the secondary.
If the secondary became unavailable, this method would always return the
address of the primary. If the primary also became unavailable, this method
would throw an exception, as an arbiter cannot handle reads.
</para>

12
reference/mongo/mongoclient/construct.xml
View file

@ -162,7 +162,7 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
</para>
<para>
The name of the replica set to connect to. If this is given, the
master will be automatically be determined. This means that 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.
</para>
@ -380,9 +380,9 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
<example>
<title><function>MongoClient::__construct</function> replica set example</title>
<para>
This example shows how to connect the driver to a replica set. It assumes
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 master could be any one of these servers.
ny1.example.com. The primary could be any one of these servers.
</para>
<programlisting role="php">
<![CDATA[
@ -392,15 +392,15 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
$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 master from this seed
// find the primary from this seed
$m2 = new MongoClient("mongodb://ny1.example.com", array("replicaSet" => "myReplSet"));
?>
]]>
</programlisting>
<para>
If the current master fails, the driver will figure out which secondary
server became the new master and automatically start using that connection.
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 <literal>replicaSet</literal>
is not specified.
</para>

2
reference/mongo/mongoclient/gethosts.xml
View file

@ -23,7 +23,7 @@
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to slaves.
information on distributing reads to secondaries.
</para>
</refsect1>

2
reference/mongo/mongocollection/batchinsert.xml
View file

@ -164,7 +164,7 @@ for ($i = 0; $i<100; $i++) {
$users[] = array('username' => 'user'.$i, 'i' => $i);
}
$mongo = new Mongo();
$mongo = new MongoClient();
$collection = $mongo->my_db->users;
$collection->drop();

2
reference/mongo/mongocollection/deleteindex.xml
View file

@ -102,7 +102,7 @@ $db->command(array("deleteIndexes" => $collection->getName(), "index" => "superf
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$c = $m->example->indices;
// create an index

20
reference/mongo/mongocollection/ensureindex.xml
View file

@ -128,20 +128,20 @@
<literal>"safe"</literal>
</para>
<para>
Starting with driver version 1.0.4, you can specify a boolean value
Starting with driver version 1.0.4, you can specify a boolean value
for checking if the index creation succeeded. The driver will throw
a MongoCursorException if index creation failed.
</para>
<para>
If you are using replication and the master has changed, using "safe"
will make the driver disconnect from the master, throw and exception,
and attempt to find a new master on the next operation (your
If you are using replication and the primary has changed, using "safe"
will make the driver disconnect from the primary, throw and exception,
and attempt to find a new primary on the next operation (your
application must decide whether or not to retry the operation on the
new master).
new primary).
</para>
<para>
If you <emphasis>do not</emphasis> use "safe" with a replica set and
the master changes, there will be no way for the driver to know about
If you <emphasis>do not</emphasis> use "safe" with a replica set and
the primary changes, there will be no way for the driver to know about
the change so it will continuously and silently fail to write.
</para>
</listitem>
@ -160,7 +160,7 @@
<literal>"timeout"</literal>
</para>
<para>
Integer, defaults to <literal>MongoCursor::$timeout</literal>. If
Integer, defaults to <literal>MongoCursor::$timeout</literal>. If
"safe" is set, this sets how long (in milliseconds) for the client to
wait for a database response. If the database does not respond within
the timeout period, a <classname>MongoCursorTimeoutException</classname>
@ -217,8 +217,8 @@
<entry>1.0.11</entry>
<entry>
<para>
The <literal>"safe"</literal> option will trigger a master failover, if
necessary.
The <literal>"safe"</literal> option will trigger a primary failover,
if necessary.
</para>
<para>
<classname>MongoException</classname> will be thrown if the index name

8
reference/mongo/mongocollection/find.xml
View file

@ -74,7 +74,7 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
@ -123,7 +123,7 @@ array(2) {
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
@ -162,7 +162,7 @@ array(3) {
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
@ -202,7 +202,7 @@ array(3) {
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');

12
reference/mongo/mongocollection/get.xml
View file

@ -14,13 +14,13 @@
</methodsynopsis>
<para>
A concise syntax for getting a collection with a dot-separated name. If a
collection name contains strange characters, you may have to use
collection name contains strange characters, you may have to use
<function>MongoDB::selectCollection</function> instead.
<programlisting role="php">
<![CDATA[
<?php
$mongo = new Mongo();
$mongo = new MongoClient();
// the following two lines are equivalent
$collection = $mongo->selectDB("foo")->selectCollection("bar.baz");
@ -32,7 +32,7 @@ $collection = $mongo->foo->bar->baz;
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
@ -44,12 +44,12 @@ $collection = $mongo->foo->bar->baz;
The next string in the collection name.
</para>
</listitem>
</varlistentry>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
&reftitle.returnvalues;
<para>
Returns the collection.
</para>
@ -73,4 +73,4 @@ End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
-->

6
reference/mongo/mongocollection/getname.xml
View file

@ -13,7 +13,7 @@
<void />
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
@ -34,7 +34,7 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$c = $m->foo->bar->baz;
echo "Working with collection " . $c->getName() . ".\n";
@ -74,4 +74,4 @@ End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
-->

4
reference/mongo/mongocollection/getreadpreference.xml
View file

@ -40,9 +40,9 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$c = $m->test->users;
$c->setReadPreference(Mongo::RP_SECONDARY, array(
$c->setReadPreference(MongoClient::RP_SECONDARY, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
array(),

2
reference/mongo/mongocollection/getslaveokay.xml
View file

@ -16,7 +16,7 @@
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to slaves.
information on distributing reads to secondaries.
</para>
</refsect1>

24
reference/mongo/mongocollection/insert.xml
View file

@ -34,7 +34,7 @@
An array.
</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
<term>
<parameter>options</parameter>
@ -48,22 +48,22 @@
<literal>"safe"</literal>
</para>
<para>
Can be a boolean or integer, defaults to &false;. If &false;, the
program continues executing without waiting for a database response.
Can be a boolean or integer, defaults to &false;. If &false;, the
program continues executing without waiting for a database response.
If &true;, the program will wait for the database response and throw a
<classname>MongoCursorException</classname> if the insert did not
succeed.
<classname>MongoCursorException</classname> if the insert did not
succeed.
</para>
<para>
If you are using replication and the master has changed, using "safe"
will make the driver disconnect from the master, throw an exception,
and attempt to find a new master on the next operation (your
If you are using replication and the primary has changed, using "safe"
will make the driver disconnect from the primary, throw an exception,
and attempt to find a new primary on the next operation (your
application must decide whether or not to retry the operation on the
new master).
new primary).
</para>
<para>
If you <emphasis>do not</emphasis> use "safe" with a replica set and
the master changes, there will be no way for the driver to know about
If you <emphasis>do not</emphasis> use "safe" with a replica set and
the primary changes, there will be no way for the driver to know about
the change so it will continuously and silently fail to write.
</para>
<para>
@ -328,7 +328,7 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');

12
reference/mongo/mongocollection/remove.xml
View file

@ -58,15 +58,15 @@
succeed.
</para>
<para>
If you are using replication and the master has changed, using "safe"
will make the driver disconnect from the master, throw and exception,
and attempt to find a new master on the next operation (your
If you are using replication and the primary has changed, using "safe"
will make the driver disconnect from the primary, throw and exception,
and attempt to find a new primary on the next operation (your
application must decide whether or not to retry the operation on the
new master).
new primary).
</para>
<para>
If you <emphasis>do not</emphasis> use "safe" with a replica set and
the master changes, there will be no way for the driver to know about
If you <emphasis>do not</emphasis> use "safe" with a replica set and
the primary changes, there will be no way for the driver to know about
the change so it will continuously and silently fail to write.
</para>
<para>

12
reference/mongo/mongocollection/save.xml
View file

@ -54,15 +54,15 @@
succeed.
</para>
<para>
If you are using replication and the master has changed, using "safe"
will make the driver disconnect from the master, throw and exception,
and attempt to find a new master on the next operation (your
If you are using replication and the primary has changed, using "safe"
will make the driver disconnect from the primary, throw and exception,
and attempt to find a new primary on the next operation (your
application must decide whether or not to retry the operation on the
new master).
new primary).
</para>
<para>
If you <emphasis>do not</emphasis> use "safe" with a replica set and
the master changes, there will be no way for the driver to know about
If you <emphasis>do not</emphasis> use "safe" with a replica set and
the primary changes, there will be no way for the driver to know about
the change so it will continuously and silently fail to write.
</para>
<para>

4
reference/mongo/mongocollection/setreadpreference.xml
View file

@ -34,12 +34,12 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$c = $m->test->users;
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$c->setReadPreference(Mongo::RP_NEAREST, array(
$c->setReadPreference(MongoClient::RP_NEAREST, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
));

2
reference/mongo/mongocollection/setslaveokay.xml
View file

@ -16,7 +16,7 @@
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to slaves.
information on distributing reads to secondaries.
</para>
</refsect1>

6
reference/mongo/mongocollection/tostring.xml
View file

@ -13,7 +13,7 @@
<void />
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
@ -34,7 +34,7 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$c1 = $m->foo->bar->baz;
echo "Working with collection $c1.";
@ -74,4 +74,4 @@ End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
-->

12
reference/mongo/mongocollection/update.xml
View file

@ -95,15 +95,15 @@
succeed.
</para>
<para>
If you are using replication and the master has changed, using "safe"
will make the driver disconnect from the master, throw an exception,
and attempt to find a new master on the next operation (your
If you are using replication and the primary has changed, using "safe"
will make the driver disconnect from the primary, throw an exception,
and attempt to find a new primary on the next operation (your
application must decide whether or not to retry the operation on the
new master).
new primary).
</para>
<para>
If you <emphasis>do not</emphasis> use "safe" with a replica set and
the master changes, there will be no way for the driver to know about
If you <emphasis>do not</emphasis> use "safe" with a replica set and
the primary changes, there will be no way for the driver to know about
the change so it will continuously and silently fail to write.
</para>
<para>

2
reference/mongo/mongoconnectionexception.xml
View file

@ -66,7 +66,7 @@
<literal>couldn't determine master</literal>
</para>
<para>
Neither server in a paired connection appeared to be master.
No server in a replica set connection was identified as the primary.
</para>
</listitem>
<listitem>

4
reference/mongo/mongocursor.xml
View file

@ -149,8 +149,8 @@ $cursor->skip(4);
<listitem>
<para>
If the query should have the "slaveOkay" flag set, which allows reads on
the slave (slaves are, by default, just for backup and unreadable). Can
be overridden with <function>MongoCursor::slaveOkay</function>.
the secondary (secondaries are, by default, just for backup and not
queried). Can be overridden with <function>MongoCursor::slaveOkay</function>.
</para>
</listitem>
</varlistentry>

8
reference/mongo/mongocursor/awaitdata.xml
View file

@ -33,13 +33,13 @@
If the cursor should wait for more data to become available.
</para>
</listitem>
</varlistentry>
</varlistentry>
</variablelist>
</para>
</refsect1>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
&reftitle.returnvalues;
<para>
Returns this cursor.
</para>
@ -65,7 +65,7 @@
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo( 'mongodb://localhost:13000', array( 'replSet' => 'seta' ) );
$m = new MongoClient( 'mongodb://localhost:13000', array( 'replSet' => 'seta' ) );
$c = $m->local->selectCollection( 'oplog.rs' );
$cursor = $c->find( array( 'ns' => 'demo.article', 'op' => 'i' ) );
$cursor->tailable( true );

2
reference/mongo/mongocursor/batchsize.xml
View file

@ -101,7 +101,7 @@
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>Mongo::batchSize</function> and combinations with
<title><function>MongoCursor::batchSize</function> and combinations with
<function>MongoCursor::limit</function></title>
<programlisting role="php">
<![CDATA[

2
reference/mongo/mongocursor/construct.xml
View file

@ -11,7 +11,7 @@
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <methodname>MongoCursor::__construct</methodname>
<methodparam><type>Mongo</type><parameter>connection</parameter></methodparam>
<methodparam><type>MongoClient</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>ns</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>query</parameter><initializer>array()</initializer></methodparam>
<methodparam choice="opt"><type>array</type><parameter>fields</parameter><initializer>array()</initializer></methodparam>

4
reference/mongo/mongocursor/doquery.xml
View file

@ -74,8 +74,8 @@
<example xml:id="mongocursor.doquery.example.basic"><!-- {{{ -->
<title><function>MongoCursor::doQuery</function> example</title>
<para>
You could override this function to attempt a query on a slave and, if that
fails, try it again on the master.
You could override this function to attempt a query on a secondary and, if
that fails, try it again on the primary.
</para>
<programlisting role="php">
<![CDATA[

4
reference/mongo/mongocursor/getreadpreference.xml
View file

@ -40,9 +40,9 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$cursor = $m->test->users->find();
$cursor->setReadPreference(Mongo::RP_SECONDARY, array(
$cursor->setReadPreference(MongoClient::RP_SECONDARY, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
array(),

2
reference/mongo/mongocursor/info.xml
View file

@ -75,7 +75,7 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$cursor = $m->foo->bar->find(array("x" => 4), array("y" => false));
var_dump($cursor->info());

2
reference/mongo/mongocursor/setflag.xml
View file

@ -76,7 +76,7 @@
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo( 'mongodb://localhost:13000', array( 'replSet' => 'seta' ) );
$m = new MongoClient( 'mongodb://localhost:13000', array( 'replSet' => 'seta' ) );
$c = $m->local->selectCollection( 'oplog.rs' );
$cursor = $c->find( array( 'ns' => 'demo.article', 'op' => 'i' ) );
$cursor->setFlag( 1, true ); // sets the tailable flag

4
reference/mongo/mongocursor/setreadpreference.xml
View file

@ -35,12 +35,12 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$cursor = $m->test->users->find();
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$cursor->setReadPreference(Mongo::RP_NEAREST, array(
$cursor->setReadPreference(MongoClient::RP_NEAREST, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
));

28
reference/mongo/mongocursor/slaveokay.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="mongocursor.slaveokay" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCursor::slaveOkay</refname>
<refpurpose>Sets whether this query can be done on a slave</refpurpose>
<refpurpose>Sets whether this query can be done on a secondary</refpurpose>
</refnamediv>
<refsect1 role="description">
@ -14,7 +14,7 @@
<methodparam choice="opt"><type>bool</type><parameter>okay</parameter><initializer>true</initializer></methodparam>
</methodsynopsis>
<para>
Calling this will make the driver route reads to slaves if:
Calling this will make the driver route reads to secondaries if:
<itemizedlist>
<listitem>
<simpara>
@ -23,13 +23,13 @@
</listitem>
<listitem>
<simpara>
You created a <classname>Mongo</classname> instance using the option
You created a <classname>MongoClient</classname> instance using the option
<literal>"replicaSet" => "setName" and</literal>
</simpara>
</listitem>
<listitem>
<simpara>
There is a healthy slave that can be reached by the driver.
There is a healthy secondary that can be reached by the driver.
</simpara>
</listitem>
</itemizedlist>
@ -38,11 +38,11 @@
<literal>server</literal> field will show which server the query was sent to.
</para>
<para>
Note that you should use this function even if you do not use the automatic
routing to slaves. If you connect directly to a secondary in a replica set,
you still need to call this function, which basically tells the database that
you are aware that you might be getting older data and you're okay with that.
If you do not call this, you'll get "not master" errors when you try to
Note that you should use this function even if you do not use the automatic
routing to secondaries. If you connect directly to a secondary in a replica
set, you still need to call this function, which basically tells the database
that you are aware that you might be getting older data and you're okay with
that. If you do not call this, you'll get "not master" errors when you try to
query.
</para>
<para>
@ -64,7 +64,7 @@
</term>
<listitem>
<para>
If it is okay to query the slave.
If it is okay to query the secondary.
</para>
</listitem>
</varlistentry>
@ -96,18 +96,18 @@
MongoCursor::$slaveOkay = false;
// cannot query slave
// cannot query secondary
$cursor = $collection->find();
// can query slave
// can query secondary
$cursor = $collection->find()->slaveOkay();
MongoCursor::$slaveOkay = true;
// can query slave
// can query secondary
$cursor = $collection->find();
// cannot query slave
// cannot query secondary
$cursor = $collection->find()->slaveOkay(false);
?>

10
reference/mongo/mongocursorexception.xml
View file

@ -17,8 +17,8 @@
just queries. Writes, commands, and any other operation that sends
information to the database and waits for a response can throw a
<classname>MongoCursorException</classname>. The only exception is
<literal>new Mongo()</literal> (creating a new connection), which will only
throw <classname>MongoConnectionException</classname>s.
<literal>new MongoClient()</literal> (creating a new connection), which will
only throw <classname>MongoConnectionException</classname>s.
</para>
<para>
@ -372,10 +372,10 @@ catch (MongoCursorException $e) {
Codes: 10107, 13435, and 10058
</para>
<para>
Not master errors, piped through by the database. Each of these will
cause the driver to disconnect and attempt to find a new master. The
Not master errors, piped through by the database. ach of these will
cause the driver to disconnect and attempt to find a new primary. The
actual error you get on failover may not be a "not master" error,
depending on when the change in master occurs.
depending on when the change in primary occurs.
</para>
</listitem>
</itemizedlist>

29
reference/mongo/mongodb.xml
View file

@ -18,7 +18,7 @@
<![CDATA[
<?php
$m = new Mongo(); // connect
$m = new MongoClient(); // connect
$db = $m->selectDB("example");
?>
@ -149,21 +149,22 @@ $db = $m->selectDB("example");
<function>MongoCollection::update</function>,
<function>MongoCollection::remove</function>,
<function>MongoCollection::save</function>, and
<function>MongoCollection::ensureIndex</function> all support safe
options). With the default value (1), a safe operation will return once
the database server has the operation. If the server goes down before
the operation has been replicated to a slave, it is possible to lose the
operation forever. Thus, you can specify <literal>w</literal> to be
higher than one and guarantee that at least one slave has the operation
before it is considered successful.
<function>MongoCollection::ensureIndex</function> all support safe
options). With the default value (1), a safe operation will return once
the database server has the operation. If the server goes down before
the operation has been replicated to a secondary, it is possible to lose
the operation forever. Thus, you can specify <literal>w</literal> to be
higher than one and guarantee that at least one secondary has the
operation before it is considered successful.
</para>
<para>
For example, if <literal>w</literal> is 2, the main server and one slave
must have a record of the operation or the driver will throw a
<classname>MongoCursorException</classname>. It is tempting to set
<literal>w</literal> to the total number of slaves + master, but then if
one slave is down the op will fail and an exception will be thrown, so
usually <literal>w=2</literal> is safest (master+1 slave).
For example, if <literal>w</literal> is 2, the primary and one secondary
must have a record of the operation or the driver will throw a
<classname>MongoCursorException</classname>. It is tempting to set
<literal>w</literal> to the total number of secondaries + primary, but
then if one secondary is down the operation will fail and an exception
will be thrown, so usually <literal>w=2</literal> is safest (primary and
one secondary).
</para>
</listitem>
</varlistentry>

28
reference/mongo/mongodb/authenticate.xml
View file

@ -14,17 +14,17 @@
<methodparam><type>string</type><parameter>password</parameter></methodparam>
</methodsynopsis>
<para>
This method causes its connection to be authenticated. If authentication is
enabled for the database server (it's not, by default), you need to log in
This method causes its connection to be authenticated. If authentication is
enabled for the database server (it's not, by default), you need to log in
before the database will allow you to do anything.
</para>
<para>
In general, you should use the authenticate built into
<function>Mongo::__construct</function> in preference to this method. If you
authenticate on connection and the connection drops and reconnects during
your session, you'll be reauthenticated. If you manually authenticated using
this method and the connection drops, you'll have to call this method again
once you're reconnected.
In general, you should use the authenticate built into
<function>MongoClient::__construct</function> in preference to this method.
If you authenticate on connection and the connection drops and reconnects
during your session, you'll be reauthenticated. If you manually
authenticated using this method and the connection drops, you'll have to call
this method again once you're reconnected.
</para>
<para>
This method is identical to running:
@ -39,7 +39,7 @@ $nonce = $db->command(array("getnonce" => 1));
$saltedHash = md5($nonce["nonce"]."${username}${hash}");
$result = $db->command(array("authenticate" => 1,
$result = $db->command(array("authenticate" => 1,
"user" => $username,
"nonce" => $nonce["nonce"],
"key" => $saltedHash
@ -50,7 +50,7 @@ $result = $db->command(array("authenticate" => 1,
</programlisting>
</para>
<para>
Once a connection has been authenticated, it can only be un-authenticated by
Once a connection has been authenticated, it can only be un-authenticated by
using the "logout" database command:
<programlisting role="php">
<![CDATA[
@ -76,7 +76,7 @@ $db->command(array("logout" => 1));
The username.
</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
<term>
<parameter>password</parameter>
@ -86,12 +86,12 @@ $db->command(array("logout" => 1));
The password (in plaintext).
</para>
</listitem>
</varlistentry>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
&reftitle.returnvalues;
<para>
Returns database response. If the login was successful, it will return
<programlisting role="php">
@ -165,4 +165,4 @@ End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
-->

2
reference/mongo/mongodb/command.xml
View file

@ -62,7 +62,7 @@ public function command($data) {
<literal>"timeout"</literal>
</para>
<para>
Integer, defaults to <literal>Mongo::$timeout</literal>. If
Integer, defaults to <literal>MongoClient::$timeout</literal>. If
"safe" is set, this sets how long (in milliseconds) for the client to
wait for a database response. If the database does not respond within
the timeout period, a <classname>MongoCursorTimeoutException</classname>

22
reference/mongo/mongodb/construct.xml
View file

@ -11,23 +11,23 @@
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <methodname>MongoDB::__construct</methodname>
<methodparam><type>Mongo</type><parameter>conn</parameter></methodparam>
<methodparam><type>MongoClient</type><parameter>conn</parameter></methodparam>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
</methodsynopsis>
<para>
This method is not meant to be called directly. The preferred way to create
an instance of MongoDB is through <function>Mongo::__get</function> or
<function>Mongo::selectDB</function>.
This method is not meant to be called directly. The preferred way to create
an instance of MongoDB is through <function>MongoClient::__get</function> or
<function>MongoClient::selectDB</function>.
</para>
<para>
If you're ignoring the previous paragraph and want to call it directly you
If you're ignoring the previous paragraph and want to call it directly you
can do so:
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$db = new MongoDB($m, 'mydbname');
?>
@ -40,7 +40,7 @@ $db = new MongoDB($m, 'mydbname');
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$db = $m->mydbname;
// or, if the name contains weird characters:
@ -51,14 +51,14 @@ $db = $m->selectDB('my,db:name');
]]>
</programlisting>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<type>Mongo</type>
<type>MongoClient</type>
<parameter>conn</parameter>
</term>
<listitem>
@ -66,7 +66,7 @@ $db = $m->selectDB('my,db:name');
Database connection.
</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
<term>
<parameter>name</parameter>
@ -76,7 +76,7 @@ $db = $m->selectDB('my,db:name');
Database name.
</para>
</listitem>
</varlistentry>
</varlistentry>
</variablelist>
</para>
</refsect1>

2
reference/mongo/mongodb/get.xml
View file

@ -20,7 +20,7 @@
<![CDATA[
<?php
$mongo = new Mongo();
$mongo = new MongoClient();
// the following two lines are equivalent
$collection = $mongo->selectDB("foo")->selectCollection("bar");

4
reference/mongo/mongodb/getreadpreference.xml
View file

@ -40,9 +40,9 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$db = $m->test;
$db->setReadPreference(Mongo::RP_SECONDARY, array(
$db->setReadPreference(MongoClient::RP_SECONDARY, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
array(),

2
reference/mongo/mongodb/getslaveokay.xml
View file

@ -16,7 +16,7 @@
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to slaves.
information on distributing reads to secondaries.
</para>
</refsect1>

2
reference/mongo/mongodb/listcollections.xml
View file

@ -74,7 +74,7 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$db = $m->selectDB("sample");
$list = $db->listCollections();

4
reference/mongo/mongodb/setreadpreference.xml
View file

@ -34,12 +34,12 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$db = $m->test;
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$db->setReadPreference(Mongo::RP_NEAREST, array(
$db->setReadPreference(MongoClient::RP_NEAREST, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
));

2
reference/mongo/mongodb/setslaveokay.xml
View file

@ -16,7 +16,7 @@
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to slaves.
information on distributing reads to secondaries.
</para>
</refsect1>

2
reference/mongo/mongoid/tostring.xml
View file

@ -35,7 +35,7 @@
<![CDATA[
<?php
$m = new Mongo();
$m = new MongoClient();
$collection = $m->selectDB("foo")->selectCollection("bar");
$collection->insert(array( "x" => "y" ));

2
reference/mongo/mongolog/setcallback.xml
View file

@ -121,7 +121,7 @@ MongoLog::setLevel(MongoLog::ALL);
MongoLog::setModule(MongoLog::ALL);
MongoLog::setCallback("callback");
new Mongo();
new MongoClient();
?>
]]>
</programlisting>

6
reference/mongo/mongopool/info.xml
View file

@ -60,9 +60,9 @@
The number of connections that could be created by this pool. For
example, suppose a pool had 5 connections remaining and 3 connections in
the pool. We could create 8 new instances of
<classname>Mongo</classname> before we exhausted this pool (assuming no
instances of <classname>Mongo</classname> went out of scope, returning
their connections to the pool).
<classname>MongoClient</classname> before we exhausted this pool
(assuming no instances of <classname>MongoClient</classname> went out of
scope, returning their connections to the pool).
</para>
<para>
A negative number means that this pool will spawn unlimited connections.

56
reference/mongo/queries.xml
View file

@ -4,7 +4,7 @@
<title>Querying</title>
<section>
<title>Distributing queries to slaves</title>
<title>Distributing queries to secondaries</title>
<note>
<title>1.1.0+</title>
@ -12,15 +12,15 @@
If you are using a
<link xlink:href="&url.mongodb.replica;">replica set</link> and version
1.1.0 or above of the driver, the driver can automatically route reads to
slaves. This behavior does not exist in earlier versions of the driver and
<emphasis>cannot</emphasis> be used with "normal" master-slave.
secondaries. This behavior does not exist in earlier versions of the driver
and <emphasis>cannot</emphasis> be used with legacy master-slave clusters.
</para>
</note>
<para>
By default, the driver will send all queries to the master. If you set the
"slaveOkay" option, the driver will send all queries to a non-primary server,
if possible. The "slaveOkay" option can be set at every "level":
By default, the driver will send all queries to the primary. If you set the
"slaveOkay" option, the driver will send read queries to a secondary server,
if possible. The "slaveOkay" option can be set at every "level":
<link linkend="mongo.setslaveokay">connection</link>,
<link linkend="mongodb.setslaveokay">database</link>,
<link linkend="mongocollection.setslaveokay">collection</link>, and
@ -42,19 +42,19 @@ $cursor = $c->find();
</programlisting>
<para>
then the query will be executed against a slave (the collection inherited
then the query will be executed against a secondary (the collection inherited
"slaveOkay" from the database and the cursor inherited it from the
collection).
</para>
<section>
<title>How slaves are chosen</title>
<title>How secondaries are chosen</title>
<para>
Each instance of <classname>Mongo</classname> chooses its own slave using
the available slave with the lowest ping time. So, if we had a PHP client
in Europe and one in Australia and we had one secondary in each of these
data centers, we could do:
Each instance of <classname>MongoClient</classname> chooses its own
secondary using the available secondary with the lowest ping time. So, if we
had a PHP client in Europe and one in Australia and we had one secondary in
each of these data centers, we could do:
</para>
<programlisting role="php">
<![CDATA[
@ -63,14 +63,14 @@ $cursor = $c->find();
// P is the primary
// on the Australian client
$m1 = new Mongo("mongodb://P", array("replicaSet" => 'setName'));
$m1 = new MongoClient("mongodb://P", array("replicaSet" => 'setName'));
$m1->foo->bar->find()->slaveOkay()->getNext();
echo "m1's slave is ".$m1->getSlave()."\n";
echo "m1's secondary is ".$m1->getSlave()."\n";
// on the European client
$m2 = new Mongo("mongodb://P", array("replicaSet" => 'setName'));
$m2 = new MongoClient("mongodb://P", array("replicaSet" => 'setName'));
$m2->foo->bar->find()->slaveOkay()->getNext();
echo "m2's slave is ".$m2->getSlave()."\n";
echo "m2's secondary is ".$m2->getSlave()."\n";
?>
]]>
@ -79,32 +79,32 @@ echo "m2's slave is ".$m2->getSlave()."\n";
we'd probably end up with something like:
</para>
<screen>
m1's slave is: australianHost
m2's slave is: europeanHost
m1's secondary is: australianHost
m2's secondary is: europeanHost
</screen>
<para>
Note that we have to do a query before a slave is chosen: slaves are chosen
lazily by the driver. <function>Mongo::getSlave</function> will return
&null; until a slave is used.
Note that we have to do a query before a secondary is chosen: secondaries
are chosen lazily by the driver. <function>Mongo::getSlave</function> will
return &null; until a secondary is used.
</para>
<para>
You can see what the driver thinks is the current status of the set members
by running <function>Mongo::getHosts</function>.
by running <function>MongoClient::getHosts</function>.
</para>
<para>
If no non-primary server is readable, the driver will send
reads to the primary (even if "slaveOkay" is set). A server is considered
readable if its state is 2 (SECONDARY) and its health is 1. You can check
this with <function>Mongo::getHosts</function>.
this with <function>MongoClient::getHosts</function>.
</para>
<para>
If you enjoy twiddling knobs that you probably shouldn't mess with, you can
request the driver to use a different slave by calling
<function>Mongo::switchSlave</function>. This may choose a new slave
request the driver to use a different secondary by calling
<function>Mongo::switchSlave</function>. This may choose a new secondary
(if one is available) and shouldn't be used unless you know what you're
doing.
</para>
@ -119,9 +119,9 @@ m2's slave is: europeanHost
</para>
<para>
The health and state of a slave is checked every 5 seconds or when the next
operation occurs after 5 seconds. It will also recheck the configuration
when the driver has a problem reaching a server.
The health and state of a secondary is checked every 5 seconds or when the
next operation occurs after 5 seconds. It will also recheck the
configuration when the driver has a problem reaching a server.
</para>
<para>

71
reference/mongo/readpreferences.xml
View file

@ -23,16 +23,16 @@
<title>Read Preference Modes</title>
<warning>
<para>
All read preference modes except <literal>Mongo::RP_PRIMARY</literal> may
return stale data as secondaries replicate operations from the primary with
some delay. Ensure that your application can tolerate stale data if you
choose to use a mode other than <literal>Mongo::RP_PRIMARY</literal>.
All read preference modes except <literal>MongoClient::RP_PRIMARY</literal>
may return stale data as secondaries replicate operations from the primary
with some delay. Ensure that your application can tolerate stale data if you
choose to use a mode other than <literal>MongoClient::RP_PRIMARY</literal>.
</para>
</warning>
<itemizedlist>
<listitem>
<para>
<literal>Mongo::RP_PRIMARY</literal>
<literal>MongoClient::RP_PRIMARY</literal>
</para>
<para>
All read operations use only the current replica set primary. This is the
@ -41,12 +41,12 @@
</para>
<para>
This mode is incompatible with use of tag sets. Specifying a tag set with
<literal>Mongo::RP_PRIMARY</literal> will result in an error.
<literal>MongoClient::RP_PRIMARY</literal> will result in an error.
</para>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_PRIMARY_PREFERRED</literal>
<literal>MongoClient::RP_PRIMARY_PREFERRED</literal>
</para>
<para>
In most situations, operations read from the primary member of the set.
@ -63,14 +63,14 @@
<para>
Version 2.2 of mongos added full support for read preferences. When
connecting to older mongos instances,
<literal>Mongo::RP_PRIMARY_PREFERRED</literal> will send queries to
<literal>MongoClient::RP_PRIMARY_PREFERRED</literal> will send queries to
secondaries.
</para>
</warning>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_SECONDARY</literal>
<literal>MongoClient::RP_SECONDARY</literal>
</para>
<para>
Operations read only from the secondary members of the set. If no
@ -85,13 +85,13 @@
<para>
When the read preference includes a tag set, the client attempts to find
secondary members that match the specified tag set and directs reads to a
random secondary from among the nearest group. If no secondaries have
random secondary from among the nearest group. If no secondaries have
matching tags, the read operation will produce an exception.
</para>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_SECONDARY_PREFERRED</literal>
<literal>MongoClient::RP_SECONDARY_PREFERRED</literal>
</para>
<para>
In most situations, operations read from secondary members, but in
@ -107,12 +107,12 @@
</listitem>
<listitem>
<para>
<literal>Mongo::RP_NEAREST</literal>
<literal>MongoClient::RP_NEAREST</literal>
</para>
<para>
The driver reads from the nearest member of the set according to the member
selection process. Reads in the <literal>Mongo::RP_NEAREST</literal> mode
do not consider the member's type and may read from both primaries and
selection process. Reads in the <literal>MongoClient::RP_NEAREST</literal>
mode do not consider the member's type and may read from both primaries and
secondaries.
</para>
<para>
@ -128,8 +128,8 @@
<para>
All operations read from the nearest member of the replica set that
matches the specified read preference mode. The
<literal>Mongo::RP_NEAREST</literal> mode prefers low latency reads over a
member's primary or secondary status.
<literal>MongoClient::RP_NEAREST</literal> mode prefers low latency reads
over a member's primary or secondary status.
</para>
</note>
</listitem>
@ -151,38 +151,39 @@
<itemizedlist>
<listitem>
<para>
<literal>Mongo::RP_PRIMARY_PREFERRED</literal>
<literal>MongoClient::RP_PRIMARY_PREFERRED</literal>
</para>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_SECONDARY</literal>
<literal>MongoClient::RP_SECONDARY</literal>
</para>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_SECONDARY_PREFERRED</literal>
<literal>MongoClient::RP_SECONDARY_PREFERRED</literal>
</para>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_NEAREST</literal>
<literal>MongoClient::RP_NEAREST</literal>
</para>
</listitem>
</itemizedlist>
<para>
You cannot specify tag sets with the <literal>Mongo::RP_PRIMARY</literal>
read preference mode. Tags apply only when selecting a secondary member of a
set, except for the when in the nearest mode.
You cannot specify tag sets with the
<literal>MongoClient::RP_PRIMARY</literal> read preference mode. Tags apply
only when selecting a secondary member of a set, except for the when in the
nearest mode.
</para>
</section>
<section>
<title>Specifying Read Preferences</title>
<para>
Read preferences may be specified in either the connection URI provided to
<function>Mongo::__construct</function>, which uses a query string syntax, or
via setter methods on the core classes, which use an array syntax for tag
sets.
<function>MongoClient::__construct</function>, which uses a query string
syntax, or via setter methods on the core classes, which use an array syntax
for tag sets.
</para>
<para>
When specifying read preference modes in a query string, the names
@ -212,13 +213,13 @@
// Prefer the nearest server with no tag preference
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
// 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 Mongo($uri, array('replicaSet' => 'rs'));
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
@ -226,7 +227,7 @@ $uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east,use:reporting';
$uri .= '&readPreferenceTags=dc:west';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
// Prefer the nearest server in the "east" data center, then a server in the
// "west" data center, and finally fall back to no tag set preference
@ -235,7 +236,7 @@ $uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$uri .= '&readPreferenceTags=dc:west';
$uri .= '&readPreferenceTags=';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
]]>
</programlisting>
</example>
@ -247,28 +248,28 @@ $m = new Mongo($uri, array('replicaSet' => 'rs'));
<![CDATA[
<?php
$m = new Mongo('mongodb://rs1.example.com,rs2.example.com', array(
$m = new MongoClient('mongodb://rs1.example.com,rs2.example.com', array(
'replicaSet' => 'rs',
));
// Prefer the nearest server with no tag preference
$m->setReadPreference(Mongo::RP_NEAREST, array());
$m->setReadPreference(MongoClient::RP_NEAREST, array());
// Prefer the nearest server in the "east" data center
$m->setReadPreference(Mongo::RP_NEAREST, array(
$m->setReadPreference(MongoClient::RP_NEAREST, array(
array('dc' => 'east'),
));
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$m->setReadPreference(Mongo::RP_NEAREST, array(
$m->setReadPreference(MongoClient::RP_NEAREST, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
));
// Prefer the nearest server in the "east" data center, then a server in the
// "west" data center, and finally fall back to no tag set preference
$m->setReadPreference(Mongo::RP_NEAREST, array(
$m->setReadPreference(MongoClient::RP_NEAREST, array(
array('dc' => 'east'),
array('dc' => 'west'),
array(),

14
reference/mongo/tutorial.xml
View file

@ -17,7 +17,7 @@
<?php
// connect
$m = new Mongo();
$m = new MongoClient();
// select a database
$db = $m->comedy;
@ -64,9 +64,9 @@ XKCD
<![CDATA[
<?php
$connection = new Mongo(); // connects to localhost:27017
$connection = new Mongo( "example.com" ); // connect to a remote host (default port: 27017)
$connection = new Mongo( "example.com:65432" ); // connect to a remote host at a given port
$connection = new MongoClient(); // connects to localhost:27017
$connection = new MongoClient( "example.com" ); // connect to a remote host (default port: 27017)
$connection = new MongoClient( "example.com:65432" ); // connect to a remote host at a given port
?>
]]>
@ -83,9 +83,9 @@ $connection = new Mongo( "example.com:65432" ); // connect to a remote host at a
covers different types of connections.
</para>
<para>
The API documentation on the <classname>Mongo</classname> class and
<function>Mongo::__construct</function> give a comprehensive look at all
possible options with a number of examples.
The API documentation on the <classname>MongoClient</classname> class and
<function>MongoClient::__construct</function> give a comprehensive look at
all possible options with a number of examples.
</para>
</section>

6
reference/mongo/writes.xml
View file

@ -68,10 +68,10 @@ $collection->insert($someDoc, array("safe" => 3));
]]>
</programlisting>
<para>
If you specify <literal>"safe" =&gt; N</literal>, the MongoDB server will
If you specify <literal>"safe" =&gt; N</literal>, the MongoDB server will
make sure that at least <literal>N</literal> servers have a copy of the write
before returning success. So, if <literal>N</literal> is 3, the master and
two slaves must have the write.
before returning success. So, if <literal>N</literal> is 3, the primary and
two secondaries must acknowledge the write.
</para>
</section>