[prev in list] [next in list] [prev in thread] [next in thread]
List: php-doc-cvs
Subject: [DOC-CVS] =?utf-8?q?svn:_/phpdoc/en/trunk/reference/mongo/_configure.xml_connecting.xml_core.xml_ini
From: Derick_Rethans <derick () php ! net>
Date: 2012-11-29 13:27:04
Message-ID: svn-derick-1354195624-328569-323470498 () svn ! php ! net
[Download RAW message or body]
derick Thu, 29 Nov 2012 13:27:04 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=328569
Log:
Fix ups, and commented some things out that aren't implemented.
Changed paths:
U phpdoc/en/trunk/reference/mongo/configure.xml
U phpdoc/en/trunk/reference/mongo/connecting.xml
U phpdoc/en/trunk/reference/mongo/core.xml
U phpdoc/en/trunk/reference/mongo/ini.xml
U phpdoc/en/trunk/reference/mongo/misc.xml
U phpdoc/en/trunk/reference/mongo/queries.xml
U phpdoc/en/trunk/reference/mongo/readpreferences.xml
U phpdoc/en/trunk/reference/mongo/testing.xml
U phpdoc/en/trunk/reference/mongo/tutorial.xml
U phpdoc/en/trunk/reference/mongo/writeconcerns.xml
["svn-diffs-328569.txt" (text/x-diff)]
Modified: phpdoc/en/trunk/reference/mongo/configure.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/configure.xml 2012-11-29 12:36:31 UTC (rev \
328568)
+++ phpdoc/en/trunk/reference/mongo/configure.xml 2012-11-29 13:27:04 UTC (rev \
328569) @@ -6,7 +6,7 @@
<para>
The MongoDB PHP driver should work on nearly any system: Windows, Mac OS X,
Unix, and Linux; little- and big-endian machines; 32- and 64-bit machines; PHP
- 5.2, 5.3 and 5.4.
+ 5.2, 5.3, 5.4 and 5.5.
</para>
<para>
&pecl.moved;
Modified: phpdoc/en/trunk/reference/mongo/connecting.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/connecting.xml 2012-11-29 12:36:31 UTC (rev \
328568)
+++ phpdoc/en/trunk/reference/mongo/connecting.xml 2012-11-29 13:27:04 UTC (rev \
328569) @@ -136,7 +136,7 @@
the configuration when the driver has a problem reaching a server.
</para>
<para>
- ReplicaSet failovers are checked every 60seconds (configurable with
+ Replica set failovers are checked every 60 seconds (configurable with
<link linkend="ini.mongo.is-master-interval">mongo.is_master_interval</link>),
and whenever a write operation fails when using acknowledged writes.
</para>
@@ -144,7 +144,7 @@
<caution>
<para>
Secondaries may be behind the primary in operations, so
- your application must be okay with getting out-of-date data when using
+ your application must be able to handle out-of-date data when using
Read Preferences other then <constant>MongoClient::RP_PRIMARY</constant>.
</para>
</caution>
@@ -197,13 +197,11 @@
<programlisting role="php">
<![CDATA[
<?php
-
// Using one server as the seed list
$m = new MongoClient("mongodb://mongos1.example.com:27017");
// Using multiple servers as the seed list
$m = new MongoClient("mongodb://mongos1.example.com:27017,mongos2.example.com:27017"));
-
?>
]]>
</programlisting>
@@ -404,13 +402,13 @@
</section>
<section xml:id="mongo.connecting.persistent">
- <title>Persistent Connections</title>
+ <title>Persistent Connections (version up to 1.1.4 *only*)</title>
<note>
<para>
This section is not relevant for 1.2.0+. In 1.2.0+, connections are always
persistent and managed automatically by the driver. If you are using a
- 1.2.x release, see <classname>MongoPool</classname> for more information on
- pooling.
+ 1.2.x release (but not 1.3.x or later), see
+ <classname>MongoPool</classname> for more information on pooling.
</para>
</note>
Modified: phpdoc/en/trunk/reference/mongo/core.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/core.xml 2012-11-29 12:36:31 UTC (rev 328568)
+++ phpdoc/en/trunk/reference/mongo/core.xml 2012-11-29 13:27:04 UTC (rev 328569)
@@ -10,7 +10,6 @@
</para>
</partintro>
- &reference.mongo.mongo;
&reference.mongo.mongoclient;
&reference.mongo.mongodb;
&reference.mongo.mongocollection;
Modified: phpdoc/en/trunk/reference/mongo/ini.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/ini.xml 2012-11-29 12:36:31 UTC (rev 328568)
+++ phpdoc/en/trunk/reference/mongo/ini.xml 2012-11-29 13:27:04 UTC (rev 328569)
@@ -238,7 +238,7 @@
<varlistentry xml:id="ini.mongo.native-long">
<term>
- <parameter>mongo.native-long</parameter>
+ <parameter>mongo.native_long</parameter>
<type>int</type>
</term>
<listitem>
Modified: phpdoc/en/trunk/reference/mongo/misc.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/misc.xml 2012-11-29 12:36:31 UTC (rev 328568)
+++ phpdoc/en/trunk/reference/mongo/misc.xml 2012-11-29 13:27:04 UTC (rev 328569)
@@ -7,5 +7,6 @@
&reference.mongo.mongolog;
&reference.mongo.mongopool;
+ &reference.mongo.mongo;
</part>
Modified: phpdoc/en/trunk/reference/mongo/queries.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/queries.xml 2012-11-29 12:36:31 UTC (rev 328568)
+++ phpdoc/en/trunk/reference/mongo/queries.xml 2012-11-29 13:27:04 UTC (rev 328569)
@@ -8,12 +8,12 @@
<para>
All queries (reads and writes) are only sent to the primary member of a
- ReplicaSet by default. This is however easily configurable by using the
+ replica set by default. This is however easily configurable by using the
<link linkend="mongo.readpreferences">Read Preferences</link> which allow
you to set some generic read preferences (such as allowing secondary reads
of the nearest server), and also provide ways to specifically target a
server in a specific country, datacenter, or even hardware, by the use of
- <link linkend="mongo.readpreferences.tagsets">ReplicaSet TagSets</link>.
+ <link linkend="mongo.readpreferences.tagsets">replica set tag sets</link>.
</para>
<para>
Read Preferences can be configured at "every level"
@@ -22,7 +22,9 @@
<member>Specifically by calling \
<methodname>MongoClient::setReadPreference</methodname></member>
<member>At the Database level with \
<methodname>MongoDB::setReadPreference</methodname></member>
<member>At the Collection level with \
<methodname>MongoCollection::setReadPreference</methodname></member> +<!--
<member>At the Cursor level with \
<methodname>MongoCursor::setReadPreference</methodname></member> +-->
</simplelist>
Each class inherits the Read Preference setting from the class above it, so if \
you do: </para>
@@ -31,20 +33,18 @@
<programlisting role="php">
<![CDATA[
<?php
-
$db->setReadPreference(MongoClient::RP_SECONDARY_PREFERRED);
$c = $db->myCollection;
$cursor = $c->find();
-
?>
]]>
</programlisting>
</example>
<para>
- then the query will be executed against a secondary (the collection inherited
- <constant>MongoClient::RP_SECONDARY_PREFERRED</constant> from the database and \
the cursor inherited it from the
- collection).
+ then the query will be executed against a secondary (the collection
+ inherited <constant>MongoClient::RP_SECONDARY_PREFERRED</constant> from the
+ database and the cursor inherited it from the collection).
</para>
</simplesect>
@@ -63,7 +63,6 @@
<?php
$options = array("replicaSet" => "setName", "readPreference" => \
MongoClient::RP_SECONDARY_PREFERRED);
-
// on the Australian client
$m = new MongoClient("mongodb://primary,australianhost.secondary,europeanhost.secondary", \
$options); $cursor = $m->foo->bar->find();
@@ -75,7 +74,6 @@
$cursor = $m->foo->bar->find();
$cursor->getNext();
echo "Reading from: ", $cursor->info()["server"], "\n";
-
?>
]]>
</programlisting>
@@ -88,14 +86,13 @@
</screen>
<para>
Note that we have to do a query before a secondary is chosen: secondaries
- are chosen lazily by the driver.
+ are chosen lazily by the driver, and for each query separately.
</para>
</example>
-
<para>
- You can see what the driver thinks is the current status of the set members
- by running <methodname>MongoClient::getHosts</methodname> or
+ You can see what the driver thinks is the current status of the set
+ members by running <methodname>MongoClient::getHosts</methodname> or
<methodname>MongoClient::getConnections</methodname>.
</para>
@@ -115,9 +112,10 @@
<title>Random notes</title>
<para>
- Writes are always sent to the primary - and by default all reads are sent
+ Writes are always sent to the primary—and by default all reads are sent
to the primary too.
</para>
+<!--
<para>
The following database commands can be sent to secondaries when using the
apropriate Read Preference:
@@ -135,37 +133,38 @@
</simplelist>
All other commands are always sent to the primary.
</para>
+-->
</simplesect>
<simplesect xml:id="mongo.queries.querying">
<title>Querying by _id</title>
<para>
- Every object inserted is automatically assigned a unique _id field, which is
- often a useful field to use in queries.
+ Every object inserted is automatically assigned a unique
+ <literal>_id</literal> field, which is often a useful field to use in
+ queries. This works similarly to "get last insert ID" functionality, except
+ that the <literal>_id</literal> is chosen by the <emphasis>client</emphasis>.
</para>
<para>
Suppose that we wish to find the document we just inserted. Inserting adds
- and _id field to the document, so we can query by that:
+ an <literal>_id</literal> field to the document, so we can query by that:
<example xml:id="mongo.queries.querying-example">
<programlisting role="php">
<![CDATA[
<?php
-
$person = array("name" => "joe");
$people->insert($person);
// now $joe has an _id field
$joe = $people->findOne(array("_id" => $person['_id']));
-
?>
]]>
</programlisting>
</example>
</para>
<para>
- Unless the user has specified otherwise, the _id field is a
+ Unless the user has specified otherwise, the <literal>_id</literal> field is a
<classname>MongoId</classname>. The most common mistake is attempting to use
a string to match a <classname>MongoId</classname>. Keep in mind that these
are two different datatypes, and will not match each other in the same way
@@ -175,7 +174,6 @@
<programlisting role="php">
<![CDATA[
<?php
-
$person = array("name" => "joe");
$people->insert($person);
@@ -185,7 +183,6 @@
// FAILS - $pid is a string, not a MongoId
$joe = $people->findOne(array("_id" => $pid));
-
?>
]]>
</programlisting>
@@ -327,30 +324,33 @@
</row>
</thead>
<tbody>
+<!--
<row>
<entry>1.3.1</entry>
<entry>
Several database commands can now be executed on secondaries.
</entry>
</row>
+-->
<row>
<entry>1.3.0</entry>
<entry>
Introduced the <link linkend="mongo.readpreferences">Read
- Preferences</link> framework to allow more fine grained controlled over
+ Preferences</link> framework to allow more fine grained control over
secondary reads.
</entry>
</row>
<row>
<entry>1.3.0</entry>
<entry>
- Deprecated <literal>slaveOkay</literal> usage.
+ Deprecated <literal>slaveOkay</literal> usage, the alternative is <link
+ linkend="mongo.readpreferences">Read Preferences</link>.
</entry>
</row>
<row>
<entry>1.1.0</entry>
<entry>
- Introduced the possiblity of routing reads to secondaries of ReplicaSet
+ Introduced the possiblity of routing reads to secondaries of replica set
members using <methodname>Mongo::setSlaveOkay</methodname>
</entry>
</row>
Modified: phpdoc/en/trunk/reference/mongo/readpreferences.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/readpreferences.xml 2012-11-29 12:36:31 UTC (rev \
328568)
+++ phpdoc/en/trunk/reference/mongo/readpreferences.xml 2012-11-29 13:27:04 UTC (rev \
328569) @@ -6,9 +6,10 @@
<para>
MongoDB 2.2 and version 1.3.0 of the driver add support for
<link xlink:href="&url.mongodb.docs.readpreferences;">read preferences</link>,
- which allow control over how queries are directed to mongod instances. Read
- preferences may be specified on either a per-connection, per-database,
- per-collection, or per-cursor basis. Preferences defined at a higher level
+ which allow control over how queries are directed to mongod instances in a
+ replica set environment. Read preferences may be specified on either a
+ per-connection, per-database, or per-collection basis. Preferences defined
+ at a higher level
will be inherited by default (e.g. <classname>MongoCollection</classname> will
inherit read perferences defined on the corresponding
<classname>MongoDB</classname> instance).
@@ -41,7 +42,7 @@
</para>
<para>
This mode is incompatible with use of tag sets. Specifying a tag set with
- <literal>MongoClient::RP_PRIMARY</literal> will result in an error.
+ <literal>MongoClient::RP_PRIMARY</literal> will result in an exception.
</para>
</listitem>
<listitem>
@@ -120,8 +121,8 @@
without preference for current or stale data.
</para>
<para>
- If you specify a tag set, the client attempts to find a secondary member
- that matches the specified tag set and directs reads to a random secondary
+ If you specify a tag set, the client attempts to find a member
+ that matches the specified tag set and directs reads to a random node
from among the nearest group.
</para>
<note>
@@ -186,7 +187,7 @@
for tag sets.
</para>
<para>
- When specifying read preference modes in a query string, the Tag sets for
+ When specifying read preference modes in a query string, the tag sets for
the <literal>readPreferenceTags</literal> value should be a comma-delimited
sequence of colon-delimited key/value pairs.
</para>
@@ -201,9 +202,9 @@
</note>
<warning>
<para>
- If the driver cannot find a matching TagSet the read will fail! It is
+ If the driver cannot find a matching tag set the read will fail! It is
your responsibility of providing suitable fallback, such as an empty
- <literal>readPreferenceTags</literal> value to fallback to "no TagSet
+ <literal>readPreferenceTags</literal> value to fallback to "no tag set
preference".
</para>
</warning>
@@ -213,13 +214,12 @@
<programlisting role="php">
<![CDATA[
<?php
-
// Prefer the nearest server with no tag preference
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
-// Prefer the nearest server in the "east" data center
+// Pick the nearest server in the "east" data center
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
@@ -259,7 +259,7 @@
// Prefer the nearest server with no tag preference
$m->setReadPreference(MongoClient::RP_NEAREST, array());
-// Prefer the nearest server in the "east" data center
+// Pick the nearest server in the "east" data center
$m->setReadPreference(MongoClient::RP_NEAREST, array(
array('dc' => 'east'),
));
Modified: phpdoc/en/trunk/reference/mongo/testing.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/testing.xml 2012-11-29 12:36:31 UTC (rev 328568)
+++ phpdoc/en/trunk/reference/mongo/testing.xml 2012-11-29 13:27:04 UTC (rev 328569)
@@ -7,10 +7,26 @@
<para>
The PECL package does not come with the tests, but they are available at
<link xlink:href="&url.mongodb.github;">Github</link>. There are two types of
- tests: the PHPUnit tests and the C tests.
+ tests: the .phpt tests and the PHPUnit tests. The PHPUnit tests are being
+ replaced by .phpt tests.
</para>
<section>
+ <title>.phpt Tests</title>
+ <para>
+ .phpt tests are the standard way of testing PHP extensions. After compiling
+ the MongoDB driver with "make" you can then issue "make test" to run the
+ tests. These tests require MongoDB to be working, and hence, you need to
+ configure the test suite itself. You do that by editting the
+ <literal>tests/mongo-test-cfg.inc</literal> file.
+ </para>
+ <para>
+ There is more information about this in the contributing guidelines on
+ <link xlink:href="https://github.com/mongodb/mongo-php-driver/blob/master/CONTRIBUTING.md#running-the-tests">GitHub</link>.
+ </para>
+ </section>
+
+ <section>
<title>PHPUnit Tests</title>
<para>
To run the tests, you must download the driver from Github (the tests are in
@@ -51,40 +67,6 @@
</section>
<section>
- <title>C Tests</title>
- <para>
- The C tests mostly check internal functions that are not exposed through PHP.
- If you'd like to run these tests, you'll need to compile PHP with the
- <literal>--enable-embed</literal> flag. Then switch to the
- <filename>tests</filename> directory and run <literal>make</literal>. This
- will create a binary called <literal>unit</literal>. Run
- <literal>unit</literal> to execute the tests. These tests do no require a
- database to be running.
- </para>
-
- <para>
- If a test passes, it will print a ".". If a test fails, it will assert and
- stop the tests. Please report any asserts.
- </para>
-
- <para>
- If <literal>make</literal> cannot find your PHP embedded library (libphp5.so)
- or header files, you may have to specify the <literal>PHP_PATH</literal>
- variable.
- </para>
-
- <para>
- Run <literal>make clean</literal> to remove all testing objects.
- </para>
-
- <para>
- If you run these tests with <filename>valgrind</filename>, you should get no
- invalid memory access errors and the "no leaks are possible" message at the
- end.
- </para>
- </section>
-
- <section>
<title>Reporting Errors</title>
<para>
Please report any failures or errors in the
Modified: phpdoc/en/trunk/reference/mongo/tutorial.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/tutorial.xml 2012-11-29 12:36:31 UTC (rev 328568)
+++ phpdoc/en/trunk/reference/mongo/tutorial.xml 2012-11-29 13:27:04 UTC (rev 328569)
@@ -63,19 +63,16 @@
<programlisting role="php">
<![CDATA[
<?php
-
$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
-
+$connection = new MongoClient( "mongodb://example.com" ); // connect to a remote \
host (default port: 27017) +$connection = new MongoClient( \
"mongodb://example.com:65432" ); // connect to a remote host at a given port ?>
]]>
</programlisting>
</example>
<para>
- You do not have to explicitly disconnect from the database. When
- <literal>$connection</literal> goes out of scope, the connection will be
- closed automatically and any database resources it was using will be freed.
+ You do not have to explicitly disconnect from the database. The driver uses
+ persistent connections and will re-use already established connections.
</para>
<section xml:id="mongo.tutorial.connecting.seealso">
<title>See Also</title>
@@ -100,9 +97,8 @@
<programlisting role="php">
<![CDATA[
<?php
-
+$connection = new MongoClient();
$db = $connection->dbname;
-
?>
]]>
</programlisting>
@@ -113,18 +109,20 @@
</para>
<para>
Be careful of typos! You can inadvertently create a new database, which can
- cause confusing errors:
+ cause confusing errors (here <literal>name</literal> is misspelled as
+ <literal>anme</literal> in the second selection:
<example xml:id="mongo.tutorial.selectdb.typo">
<programlisting role="php">
<![CDATA[
<?php
+$connection = new MongoClient();
$db = $connection->mybiglongdbname;
// do some stuff
+
$db = $connection->mybiglongdbanme;
// now connected to a different database!
-
?>
]]>
</programlisting>
@@ -148,13 +146,14 @@
<programlisting role="php">
<![CDATA[
<?php
+$connection = new MongoClient();
+$db = $connection->baz;
-$db = $connection->baz;
+// select a collection:
$collection = $db->foobar;
-// or, more succinctly
+// or, directly selecting a database and collection:
$collection = $connection->baz->foobar;
-
?>
]]>
</programlisting>
@@ -182,20 +181,23 @@
<programlisting role="php">
<![CDATA[
<?php
-
-$doc = array( "name" => "MongoDB",
- "type" => "database",
- "count" => 1,
- "info" => (object)array( "x" => 203, "y" => 102),
- "versions" => array("0.9.7", "0.9.8", "0.9.9")
+$doc = array(
+ "name" => "MongoDB",
+ "type" => "database",
+ "count" => 1,
+ "info" => (object)array( "x" => 203, "y" => 102),
+ "versions" => array("0.9.7", "0.9.8", "0.9.9")
);
-
?>
]]>
</programlisting>
</example>
<para>
- Note that you can have nested arrays and objects.
+ Note that you can have nested arrays and objects. The driver will always
+ store an associative array as an object in the database. A
+ numerically indexed array is stored as an array in case the keys start at
+ 0 and are not interrupted, and as an object if the array keys don't start
+ at 0 or have gaps (ie: <literal>0, 1, 4, 5</literal>).
</para>
<para>
To insert this document, use <function>MongoCollection::insert</function>:
@@ -204,9 +206,10 @@
<programlisting role="php">
<![CDATA[
<?php
+$connection = new MongoClient();
+$collection = $connection->database->collectionName;
$collection->insert( $doc );
-
?>
]]>
</programlisting>
@@ -225,19 +228,21 @@
Finding Documents using <function>MongoCollection::findOne</function>
</title>
<para>
- To show that the document we inserted in the previous step is there, we can
- do a simple <function>MongoCollection::findOne</function> operation to get a
- single document from the collection. This method is useful when there only is
- one document matching the query or you are only interested in one result.
+ To show that the document we inserted in the previous step is stored in
+ the database, we can do a simple
+ <function>MongoCollection::findOne</function> operation to get a single
+ document from the collection. This method is useful when there is only one
+ document matching the query or you are only interested in one result.
</para>
<example xml:id="mongo.tutorial.findone-example">
<programlisting role="php">
<![CDATA[
<?php
+$connection = new MongoClient();
+$collection = $connection->database->collectionName;
$obj = $collection->findOne();
var_dump( $obj );
-
?>
]]>
</programlisting>
@@ -290,6 +295,8 @@
<programlisting role="php">
<![CDATA[
<?php
+$connection = new MongoClient();
+$db = $connection->database;
$db->foo->insert(array("_id" => 1));
// this will throw an exception
@@ -297,18 +304,16 @@
// this is fine, as it is a different collection
$db->bar->insert(array("_id" => 1));
-
?>
]]>
</programlisting>
</example>
<para>
- By default the driver will ensure the servers has acknowledged the write
+ By default the driver will ensure the server has acknowledged the write
before returning. You can optionally turn this behaviour off by passing
- <literal>array("w" => 0)</literal> as the second argument -
- <literal>array("w" => 1)</literal>. meaning the driver should not wait
- for the database to acknowledge the writes, so the driver would not throw
- the duplicate <literal>_id</literal> exception.
+ <literal>array("w" => 0)</literal> as the second argument. This means that
+ the driver should not wait for the database to acknowledge the write and
+ would not throw the duplicate <literal>_id</literal> exception.
</para>
<section xml:id="mongo.tutorial.findone.seealso">
<title>See Also</title>
@@ -339,20 +344,24 @@
<programlisting role="php">
<![CDATA[
<?php
+$connection = new MongoClient();
+$collection = $connection->database->collectionName;
-for($i=0; $i<100; $i++) {
- $collection->insert( array( "i" => $i ) );
+for ( $i = 0; $i < 100; $i++ )
+{
+ $collection->insert( array( 'i' => $i, "field{$i}" => $i * 2 ) );
}
-
?>
]]>
</programlisting>
</example>
<para>
- Notice that we can insert arrays with different key sets into the same
+ Notice that we can insert arrays with different keys into the same
collection. This aspect is what we mean when we say that MongoDB is
- "schema-free".
+ "schema-free". In the example above each document has an
+ <literal>i</literal> field, but also a field name in the form of
+ <literal>field</literal> + <literal>$i</literal>.
</para>
</section>
@@ -366,9 +375,10 @@
<programlisting role="php">
<![CDATA[
<?php
+$connection = new MongoClient();
+$collection = $connection->database->collectionName;
echo $collection->count();
-
?>
]]>
</programlisting>
@@ -390,13 +400,15 @@
<programlisting role="php">
<![CDATA[
<?php
+$connection = new MongoClient();
+$collection = $connection->database->collectionName;
$cursor = $collection->find();
-foreach ($cursor as $id => $value) {
+foreach ( $cursor as $id => $value )
+{
echo "$id: ";
var_dump( $value );
}
-
?>
]]>
</programlisting>
@@ -421,20 +433,23 @@
We can create a query to pass to the
<function>MongoCollection::find</function> method to get a subset of the
documents in our collection. For example, if we wanted to find the document
- for which the value of the "i" field is 71, we would do the following:
+ for which the value of the <literal>"i"</literal> field is
+ <literal>71</literal>, we would do the following:
</para>
<example xml:id="mongo.tutorial.criteria-example">
<programlisting role="php">
<![CDATA[
<?php
+$connection = new MongoClient();
+$collection = $connection->database->collectionName;
-$query = array( "i" => 71 );
+$query = array( 'i' => 71 );
$cursor = $collection->find( $query );
-while( $cursor->hasNext() ) {
+while ( $cursor->hasNext() )
+{
var_dump( $cursor->getNext() );
}
-
?>
]]>
</programlisting>
@@ -459,38 +474,44 @@
<title>Getting A Set of Documents With a Query</title>
<para>
We can use the query to get a set of documents from our collection. For
- example, if we wanted to get all documents where "i" > 50, we could write:
+ example, if we wanted to get all documents where <literal>"i"</literal>
+ > <literal>50</literal>, we could write:
</para>
<example xml:id="mongo.tutorial.multi.query-example">
<programlisting role="php">
<![CDATA[
<?php
+$connection = new MongoClient();
+$collection = $connection->database->collectionName;
$query = array( "i" => array( '$gt' => 50 ) ); //note the single quotes around '$gt'
$cursor = $coll->find( $query );
-while( $cursor->hasNext() ) {
+while ( $cursor->hasNext() )
+{
var_dump( $cursor->getNext() );
}
-
?>
]]>
</programlisting>
<para>
- which should print the documents where i > 50. We could also get a range, \
say
- 20 < i <= 30:
+ which should print the documents where <literal>"i"</literal> >
+ <literal>50</literal>. We could also get a range, say
+ <literal>20 < i <= 30</literal>:
</para>
<screen>
<![CDATA[
<?php
+$connection = new MongoClient();
+$collection = $connection->database->collectionName;
-$query = array( "i" => array( "\$gt" => 20, "\$lte" => 30 ) );
+$query = array( 'i' => array( '$gt' => 20, "\$lte" => 30 ) );
$cursor = $coll->find( $query );
-while( $cursor->hasNext() ) {
+while ( $cursor->hasNext() )
+{
var_dump( $cursor->getNext() );
}
-
?>
]]>
</screen>
@@ -512,10 +533,11 @@
<programlisting role="php">
<![CDATA[
<?php
+$connection = new MongoClient();
+$collection = $connection->database->collectionName;
$coll->ensureIndex( array( "i" => 1 ) ); // create index on "i"
$coll->ensureIndex( array( "i" => -1, "j" => 1 ) ); // index on "i" descending, "j" \
ascending
-
?>
]]>
</programlisting>
Modified: phpdoc/en/trunk/reference/mongo/writeconcerns.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/writeconcerns.xml 2012-11-29 12:36:31 UTC (rev \
328568)
+++ phpdoc/en/trunk/reference/mongo/writeconcerns.xml 2012-11-29 13:27:04 UTC (rev \
328569) @@ -37,19 +37,19 @@
</warning>
<para>
- When using acknowledged writes and the ReplicaSet has failedover, the driver
+ When using acknowledged writes and the replica set has failed over, the driver
will automatically 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 primary).
</para>
<para>
- When using unacknowledged writes (w=0) and the ReplicaSet has failedover,
+ When using unacknowledged writes (w=0) and the replica set has failed over,
there will be no way for the driver to know about the change so it will
- continuously and silently fail to write.
+ continue and silently fail to write.
</para>
<para>
The default Write Concern for the <classname>MongoClient</classname> is
- <literal>1</literal>, acknowledge.
+ <literal>1</literal>: acknowledge write operations.
</para>
@@ -65,11 +65,13 @@
</row>
</thead>
<tbody>
+<!--
<row>
<entry>w=-1</entry>
<entry>Errors ignored</entry>
<entry>No errors, including network errors, will be checked at all</entry>
</row>
+-->
<row>
<entry>w=0</entry>
<entry>Unacknowledged</entry>
@@ -78,23 +80,23 @@
<row>
<entry>w=1</entry>
<entry>Acknowledged</entry>
- <entry>The write will be acknowledged by the server (the primary on ReplicaSet \
configuration)</entry> + <entry>The write will be acknowledged by the server \
(the primary on replica set configuration)</entry> </row>
<row>
<entry>w=N</entry>
- <entry>ReplicaSet Acknowledged</entry>
+ <entry>Replica Set Acknowledged</entry>
<entry>The write will be acknowledged by the primary server, and
replicated to <literal>N-1</literal> secondaries.</entry>
</row>
<row>
<entry>w=majority</entry>
<entry>Majority Acknowledged</entry>
- <entry>The write will be acknowledged by the majority of the ReplicaSet \
(including the primary). This is a special reserved string.</entry> + <entry>The \
write will be acknowledged by the majority of the replica set (including the \
primary). This is a special reserved string.</entry> </row>
<row>
<entry>w=<tag set></entry>
- <entry>ReplicaSet TagSet Acknowledged</entry>
- <entry>The write will be acknowledged by members of the entire TagSet</entry>
+ <entry>Replica Set Tag Set Acknowledged</entry>
+ <entry>The write will be acknowledged by members of the entire tag set</entry>
</row>
<row>
<entry>j=true</entry>
@@ -110,11 +112,11 @@
<simplesect xml:id="mongo.writeconcerns.unacknowledged">
<title>Unacknowledged Writes</title>
<para>
- By not requiring the server to acknowledge writes means that writes can be \
performed + By not requiring the server to acknowledge writes the writes can be \
performed extremely quickly, but you don't know whether or not they actually \
succeeded. Writes can fail for a number of reasons: if there are network problems, \
if a database server goes down, or if the write was simply invalid (e.g., writing
- to a system collection).
+ to a system collection; or duplicate key errors).
</para>
<para>
While developing, you should always use acknowledged writes (to protect against
@@ -125,8 +127,8 @@
thousands of records per second.
</para>
<para>
- It is strongly recommended that you do a acknowledged write at the end of
- series of unacknowledged writes. Doing so will not incurr in too large
+ It is strongly recommended that you do an acknowledged write at the end of
+ series of unacknowledged writes. Doing so will not incur in a too large
performance penalty, but still allow you to catch any errors that may have
occurred.
</para>
@@ -159,14 +161,14 @@
<simplesect xml:id="mongo.writeconcerns.acknowledged">
<title>Acknowledged Writes</title>
<para>
- These type of write operations will make sure that the
- database has the write before returning success. If the write failed, it
- will throw a <classname>MongoCursorException</classname> with an explanation of
- the failure. The <classname>MongoClient</classname> default behaviour is to
- acknowledge the write (w=1).
+ These type of write operations will make sure that the database has
+ accepted the write operation before returning success. If the write failed,
+ it will throw a <classname>MongoCursorException</classname> with an
+ explanation of the failure. The <classname>MongoClient</classname> default
+ behaviour is to acknowledge the write (w=1).
</para>
<para>
- It is possible to specify how many members of an ReplicaSet have to
+ It is possible to specify how many members of an replica set have to
acknowledge the write (i.e. have it replicated) before the write is deemed
acknowledged and the operation returns.
<example xml:id="mongo.writeconcerns.acknowledged-example">
@@ -176,28 +178,31 @@
<?php
// Force acknowledgement from the primary only
$collection->insert($doc, array("w" => 1));
-// Force acknowledgement from the primary, and one other member of the ReplicaSet
+
+// Force acknowledgement from the primary, and one other member of the
+// replica set
$collection->insert($doc, array("w" => 2));
-// Force acknowledgement from the primary, and six other member of the ReplicaSet
-// (You probably never ever want to do this :)
+
+// Force acknowledgement from the primary, and six other members of the
+// replica set (you probably never should do this):
$collection->insert($doc, array("w" => 7));
]]>
</programlisting>
<para>
Keep in mind to select your Write Concern carefully. If you have a
- ReplicaSet with 5 members, and you select WriteConcern of
+ replica set with 5 members, and you select Write Concern of
<literal>4</literal> you will risk the write blocking forever when one
- member of the ReplicaSet goes down for maintenance or a temporary network
+ member of the replica set goes down for maintenance or a temporary network
outage happens.
</para>
</example>
</para>
<warning>
<para>
- Passing in a string value for WriteConcern has a specific meaning
- (ReplicaSet TagSet Acknowledged). Please be careful of
+ Passing in a string value for Write Concern has a specific meaning
+ (Replica Set Tag Set Acknowledged). Please be careful of
<emphasis>NOT</emphasis> using string values for numbers (i.e.
- <literal>array("w" => "1")</literal>) as it will be treated as a TagSet
+ <literal>array("w" => "1")</literal>) as it will be treated as a tag set
name.
</para>
</warning>
@@ -208,7 +213,7 @@
<para>
Using the special <literal>majority</literal> Write Concern option is the
recommended way for writes that are required to survive the apocalypse, as
- it will ensure the majority of your ReplicaSet will have the write and will
+ it will ensure the majority of your replica set will have the write and will
therefore be guaranteed to survive all usual suspect outage scenarios.
</para>
<example xml:id="mongo.writeconcerns.majority.acknowledged-example">
@@ -232,10 +237,10 @@
<simplesect xml:id="mongo.writeconcerns.journal">
<title>Journaled Writes</title>
<para>
- When connecting to a ReplicaSet the default WriteConcern is only to have
- the primary server acknowledge the write, but there is a 100ms window until
- the write gets journaled and flushed to disk. It is possible to force the
- write to be journaled before acknowledging the write by setting the
+ When connecting to a replica set the default Write Concern is only to have
+ the primary server acknowledge the write. There is however a 100ms window
+ until the write gets journaled and flushed to disk. It is possible to force
+ the write to be journaled before acknowledging the write by setting the
<literal>j</literal> option:
<example xml:id="mongo.writeconcerns.journalled">
<title>Acknowledged and Journaled Write</title>
@@ -290,8 +295,9 @@
<row>
<entry>1.3.0</entry>
<entry>
- The <literal>"safe"</literal> write option has been deprecated and not
- available with the new <classname>MongoClient</classname> class.
+ The <literal>"safe"</literal> write option has been deprecated and is
+ not available with the new <classname>MongoClient</classname> class.
+ Use the <literal>"w"</literal> option instead.
</entry>
</row>
</tbody>
--
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic