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

- Update some examples and paragraphs to use WriteConcerns

Browse source 
- Update all options to include the WriteConcern option - and refactored those options into entities


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328543 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Hannes Magnusson 2012-11-28 19:31:57 +00:00
parent 5f2e83dfc2
commit 26b9276e07
19 changed files with 85 additions and 341 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
language-snippets.ent
View file

@ -1721,3 +1721,7 @@ tag sets, where each tag set is itself an array of criteria used to match tags
on replica set members.</para></listitem></varlistentry></variablelist>
'>
<!ENTITY mongo.setreadpreference.return '<para xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</para>'>
<!ENTITY mongo.writes.parameters.writeconcern '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"w"</literal></para><para>See <link linkend="mongo.writeconcerns">WriteConcerns</link>. The default value for <classname>MongoClient</classname> is <literal>1</literal>.</para></listitem>'>
<!ENTITY mongo.writes.parameters.fsync '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"fsync"</literal></para><para>Boolean, defaults to &false;. Forces the insert to be synced to disk before returning success. If &true;, an acknowledged insert is implied and will override setting <literal>w</literal> to <literal>0</literal>.</para></listitem>'>
<!ENTITY mongo.writes.parameters.timeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"timeout"</literal></para><para>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> will be thrown.</para></listitem>'>
<!ENTITY mongo.writes.parameters.safe '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"safe"</literal></para><para><emphasis>Deprecated</emphasis>. Please use the <link linkend="mongo.writeconcerns">WriteConcern</link> <literal>w</literal> option.</para></listitem>'>

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

@ -191,8 +191,9 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
<literal>"w"</literal>
</para>
<para>
The <literal>w</literal> option specifies the write concern for the
driver, which determines how long the driver blocks when writing. The
The <literal>w</literal> option specifies the
<link linkend="mongo.writeconcerns">Write Concern</link> for the driver,
which determines how long the driver blocks when writing. The
default value is <literal>1</literal>.
</para>
<para>
@ -211,11 +212,6 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
and ensures that the write operation has been applied to the majority
(more than 50%) of the participating nodes.
</para>
<para>
See the <link
xlink:href="&url.mongodb.docs;applications/replication/#replica-set-write-concern">core
documentation</link> on replica sets for more information.
</para>
</listitem>
<listitem>
<para>

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

@ -125,7 +125,7 @@ $data = array (
'foo' => 5,
),
);
$d = $c->insert($data, array("safe" => true));
$d = $c->insert($data, array("w" => 1));
$ops = array(
array(

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

@ -38,34 +38,9 @@
<para>
Options for the inserts.
<itemizedlist>
<listitem>
<para>
<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.
If &true;, the program will wait for the database response and throw a
<classname>MongoCursorException</classname> if the insert did not
succeed.
</para>
<para>
If <literal>safe</literal> is an integer, will replicate the
insert to that many machines before returning success (or throw an
exception if the replication times out, see wtimeout). This overrides
the w variable set on the collection.
</para>
</listitem>
<listitem>
<para>
<literal>"fsync"</literal>
</para>
<para>
Boolean, defaults to &false;. Forces the insert to be synced to
disk before returning success. If &true;, a safe insert is implied
and will override setting <literal>safe</literal> to &false;.
</para>
</listitem>
&mongo.writes.parameters.writeconcern;
&mongo.writes.parameters.fsync;
&mongo.writes.parameters.timeout;
<listitem>
<para>
<literal>"continueOnError"</literal>
@ -80,6 +55,7 @@
<function>MongoDB::lastError</function>.
</para>
</listitem>
&mongo.writes.parameters.safe;
</itemizedlist>
</para>
</listitem>

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

@ -63,7 +63,7 @@ $c = $db->distinct;
$c->insert(array("stuff" => "bar", "zip-code" => 10010));
$c->insert(array("stuff" => "foo", "zip-code" => 10010));
$c->insert(array("stuff" => "bar", "zip-code" => 99701), array("safe" => true));
$c->insert(array("stuff" => "bar", "zip-code" => 99701), array("w" => 1));
$retval = $c->distinct("zip-code");
var_dump($retval);

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

@ -51,6 +51,7 @@
<literal>array("optionname" => &lt;boolean&gt;, ...)</literal>. Currently
supported options are:
<itemizedlist>
&mongo.writes.parameters.writeconcern;
<listitem>
<para>
<literal>"unique"</literal>
@ -123,28 +124,6 @@
</para>
</warning>
</listitem>
<listitem>
<para>
<literal>"safe"</literal>
</para>
<para>
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 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 primary).
</para>
<para>
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>
<listitem>
<para>
<literal>"name"</literal>
@ -155,18 +134,8 @@
about the index name being too long.
</para>
</listitem>
<listitem>
<para>
<literal>"timeout"</literal>
</para>
<para>
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>
will be thrown.
</para>
</listitem>
&mongo.writes.parameters.timeout;
&mongo.writes.parameters.safe;
</itemizedlist>
</para>
</listitem>

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

@ -165,7 +165,7 @@ $col->insert(array(
"priority" => 2,
"tasks" => array( "run marketing report", "email report" )
),
array("safe" => true)
array("w" => 1)
);

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

@ -43,58 +43,10 @@
<para>
Options for the insert.
<itemizedlist>
<listitem>
<para>
<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.
If &true;, the program will wait for the database response and throw a
<classname>MongoCursorException</classname> if the insert did not
succeed.
</para>
<para>
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 primary).
</para>
<para>
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>
If <literal>safe</literal> is an integer, will replicate the
insert to that many machines before returning success (or throw an
exception if the replication times out, see wtimeout). This overrides
the w variable set on the collection.
</para>
</listitem>
<listitem>
<para>
<literal>"fsync"</literal>
</para>
<para>
Boolean, defaults to &false;. Forces the insert to be synced to
disk before returning success. If &true;, a safe insert is implied
and will override setting <literal>safe</literal> to &false;.
</para>
</listitem>
<listitem>
<para>
<literal>"timeout"</literal>
</para>
<para>
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>
will be thrown.
</para>
</listitem>
&mongo.writes.parameters.writeconcern;
&mongo.writes.parameters.fsync;
&mongo.writes.parameters.timeout;
&mongo.writes.parameters.safe;
</itemizedlist>
</para>
</listitem>
@ -107,7 +59,7 @@
&reftitle.returnvalues;
<para>
Returns an array containing the status of the insertion if the
<literal>"safe"</literal> option is set. Otherwise, returns &true; if the
<literal>"w"</literal> option is set. Otherwise, returns &true; if the
inserted array is not empty (a <classname>MongoException</classname> will be
thrown if the inserted array is empty).
</para>
@ -239,11 +191,11 @@
</para>
<para>
Throws <classname>MongoCursorException</classname> if the
<literal>"safe"</literal> option is set and the operation fails.
<literal>"w"</literal> option is set and the operation fails.
</para>
<para>
Throws <classname>MongoCursorTimeoutException</classname> if the
<literal>"safe"</literal> option is set and the operation takes longer than
<literal>"w"</literal> option is set and the operation takes longer than
<varname>MongoCursor::$timeout</varname> milliseconds to complete. This does
not kill the operation on the server; it is a client-side timeout.
</para>
@ -265,8 +217,9 @@
<entry>1.3.0</entry>
<entry>
The <parameter>options</parameter> parameter no longer accepts a boolean
to signify a safe insert. Instead, this now has to be done with
<literal>array('safe' => true)</literal>.
to signify a acknowledged write. Instead, this now has to be done with
<literal>array('w' => 1)</literal> (The default behaviour of
<classname>MongoClient</classname>).
</entry>
</row>
<row>
@ -363,23 +316,23 @@ array(12) {
</example>
<example>
<title><function>MongoCollection::insert</function> safe example</title>
<title><function>MongoCollection::insert</function> acknowledged write example</title>
<para>
This example shows inserting two elements with the same _id, which causes
a <classname>MongoCursorException</classname> to be thrown, as
<parameter>safe</parameter> was set.
<parameter>w</parameter> was set.
</para>
<programlisting role="php">
<![CDATA[
<?php
$person = array("name" => "Joe", "age" => 20);
$collection->insert($person, true);
$collection->insert($person);
// now $person has an _id field, so if we save it
// again, we will get an exception
try {
$collection->insert($person, true);
$collection->insert($person, array("w" => 1));
} catch(MongoCursorException $e) {
echo "Can't save the same person twice!\n";
}

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

@ -38,6 +38,7 @@
<para>
Options for remove.
<itemizedlist>
&mongo.writes.parameters.writeconcern;
<listitem>
<para>
<literal>"justOne"</literal>
@ -46,58 +47,9 @@
Remove at most one record matching this criteria.
</para>
</listitem>
<listitem>
<para>
<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.
If &true;, the program will wait for the database response and throw a
<classname>MongoCursorException</classname> if the update did not
succeed.
</para>
<para>
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 primary).
</para>
<para>
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>
If <literal>safe</literal> is an integer, will replicate the
update to that many machines before returning success (or throw an
exception if the replication times out, see wtimeout). This overrides
the w variable set on the collection.
</para>
</listitem>
<listitem>
<para>
<literal>"fsync"</literal>
</para>
<para>
Boolean, defaults to &false;. Forces the update to be synced to
disk before returning success. If &true;, a safe update is implied
and will override setting <literal>safe</literal> to &false;.
</para>
</listitem>
<listitem>
<para>
<literal>"timeout"</literal>
</para>
<para>
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>
will be thrown.
</para>
</listitem>
&mongo.writes.parameters.fsync;
&mongo.writes.parameters.timeout;
&mongo.writes.parameters.safe;
</itemizedlist>
</para>
</listitem>
@ -110,7 +62,7 @@
&reftitle.returnvalues;
<para>
Returns an array containing the status of the removal if the
<literal>"safe"</literal> option is set. Otherwise, returns &true;.
<literal>"w"</literal> option is set. Otherwise, returns &true;.
</para>
<para>
Fields in the status array are described in the documentation for
@ -122,11 +74,11 @@
&reftitle.errors;
<para>
Throws <classname>MongoCursorException</classname> if the
<literal>"safe"</literal> option is set and the operation fails.
<literal>"w"</literal> option is set and the operation fails.
</para>
<para>
Throws <classname>MongoCursorTimeoutException</classname> if the
<literal>"safe"</literal> option is set and the operation takes longer than
<literal>"w"</literal> option is set and the operation takes longer than
<varname>MongoCursor::$timeout</varname> milliseconds to complete. This does
not kill the operation on the server; it is a client-side timeout.
</para>

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

@ -42,58 +42,10 @@
<para>
Options for the save.
<itemizedlist>
<listitem>
<para>
<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.
If &true;, the program will wait for the database response and throw a
<classname>MongoCursorException</classname> if the insert did not
succeed.
</para>
<para>
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 primary).
</para>
<para>
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>
If <literal>safe</literal> is an integer, will replicate the
insert to that many machines before returning success (or throw an
exception if the replication times out, see wtimeout). This overrides
the w variable set on the collection.
</para>
</listitem>
<listitem>
<para>
<literal>"fsync"</literal>
</para>
<para>
Boolean, defaults to &false;. Forces the insert to be synced to
disk before returning success. If &true;, a safe insert is implied
and will override setting <literal>safe</literal> to &false;.
</para>
</listitem>
<listitem>
<para>
<literal>"timeout"</literal>
</para>
<para>
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>
will be thrown.
</para>
</listitem>
&mongo.writes.parameters.writeconcern;
&mongo.writes.parameters.fsync;
&mongo.writes.parameters.timeout;
&mongo.writes.parameters.safe;
</itemizedlist>
</para>
</listitem>

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

@ -51,6 +51,7 @@
<literal>array("optionname" => &lt;boolean&gt;, ...)</literal>. Currently
supported options are:
<itemizedlist>
&mongo.writes.parameters.writeconcern;
<listitem>
<para>
<literal>"upsert"</literal>
@ -83,58 +84,9 @@
may change its default behavior at some point in the future.
</para>
</listitem>
<listitem>
<para>
<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.
If &true;, the program will wait for the database response and throw a
<classname>MongoCursorException</classname> if the update did not
succeed.
</para>
<para>
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 primary).
</para>
<para>
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>
If <literal>safe</literal> is an integer, will replicate the
update to that many machines before returning success (or throw an
exception if the replication times out, see wtimeout). This overrides
the w variable set on the collection.
</para>
</listitem>
<listitem>
<para>
<literal>"fsync"</literal>
</para>
<para>
Boolean, defaults to &false;. Forces the update to be synced to
disk before returning success. If &true;, a safe update is implied
and will override setting <literal>safe</literal> to &false;.
</para>
</listitem>
<listitem>
<para>
<literal>"timeout"</literal>
</para>
<para>
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>
will be thrown.
</para>
</listitem>
&mongo.writes.parameters.fsync;
&mongo.writes.parameters.timeout;
&mongo.writes.parameters.safe;
</itemizedlist>
</para>
</listitem>
@ -147,7 +99,7 @@
&reftitle.returnvalues;
<para>
Returns an array containing the status of the update if the
<literal>"safe"</literal> option is set. Otherwise, returns &true;.
<literal>"w"</literal> option is set. Otherwise, returns &true;.
</para>
<para>
Fields in the status array are described in the documentation for
@ -159,11 +111,11 @@
&reftitle.errors;
<para>
Throws <classname>MongoCursorException</classname> if the
<literal>"safe"</literal> option is set and the operation fails.
<literal>"w"</literal> option is set and the operation fails.
</para>
<para>
Throws <classname>MongoCursorTimeoutException</classname> if the
<literal>"safe"</literal> option is set and the operation takes longer than
<literal>"w"</literal> option is set and the operation takes longer than
<varname>MongoCursor::$timeout</varname> milliseconds to complete. This does
not kill the operation on the server; it is a client-side timeout.
</para>

4
reference/mongo/mongocursorexception.xml
View file

@ -33,8 +33,8 @@
<?php
try {
$collection->insert(array("_id" => 1), array("safe" => true));
$collection->insert(array("_id" => 1), array("safe" => true));
$collection->insert(array("_id" => 1), array("w" => 1));
$collection->insert(array("_id" => 1), array("w" => 1));
}
catch (MongoCursorException $e) {
echo "error message: ".$e->getMessage()."\n";

7
reference/mongo/mongodb.xml
View file

@ -144,13 +144,14 @@ $db = $m->selectDB("example");
version 1.5.1+ of the MongoDB server and 1.0.8+ of the driver.
</para>
<para>
<literal>w</literal> is used whenever you perform a "safe" operation
<literal>w</literal> is used whenever you need to adjust the
acknowledgement level
(<function>MongoCollection::insert</function>,
<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
<function>MongoCollection::ensureIndex</function> all support this
option). With the default value (1), an acknowledged 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

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

@ -57,18 +57,7 @@ public function command($data) {
<literal>array("optionname" => &lt;boolean&gt;, ...)</literal>. Currently
supported options are:
<itemizedlist>
<listitem>
<para>
<literal>"timeout"</literal>
</para>
<para>
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>
will be thrown.
</para>
</listitem>
&mongo.writes.parameters.timeout;
</itemizedlist>
</para>
</listitem>

9
reference/mongo/mongogridfs/remove.xml
View file

@ -39,14 +39,7 @@
Options for the remove. Valid options are:
</para>
<itemizedlist>
<listitem>
<para>
<literal>"safe"</literal>
</para>
<para>
Check that the remove succeeded.
</para>
</listitem>
&mongo.writes.parameters.writeconcern;
</itemizedlist>
</listitem>
</varlistentry>

11
reference/mongo/mongogridfs/storebytes.xml
View file

@ -49,14 +49,7 @@
<para>
Options for the store.
<itemizedlist>
<listitem>
<para>
<literal>"safe"</literal>
</para>
<para>
Check that this store succeeded.
</para>
</listitem>
&mongo.writes.parameters.writeconcern;
</itemizedlist>
</para>
</listitem>
@ -75,7 +68,7 @@
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoCursorException</classname> if the "safe" option is
Throws <classname>MongoCursorException</classname> if the "w" option is
set and the insert fails.
</para>
</refsect1>

11
reference/mongo/mongogridfs/storefile.xml
View file

@ -49,14 +49,7 @@
<para>
Options for the store.
<itemizedlist>
<listitem>
<para>
<literal>"safe"</literal>
</para>
<para>
Check that this store succeeded.
</para>
</listitem>
&mongo.writes.parameters.writeconcern;
</itemizedlist>
</para>
</listitem>
@ -75,7 +68,7 @@
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoCursorException</classname> if the "safe" option is
Throws <classname>MongoCursorException</classname> if the "w" option is
set and the insert fails.
</para>
</refsect1>

6
reference/mongo/tutorial.xml
View file

@ -291,12 +291,12 @@ array(6) {
<![CDATA[
<?php
$db->foo->insert(array("_id" => 1), array("safe" => true));
$db->foo->insert(array("_id" => 1), array("w" => 1));
// this will throw an exception
$db->foo->insert(array("_id" => 1), array("safe" => true));
$db->foo->insert(array("_id" => 1), array("w" => 1));
// this is fine, as it is a different collection
$db->bar->insert(array("_id" => 1), array("safe" => true));
$db->bar->insert(array("_id" => 1), array("w" => 1));
?>
]]>

21
reference/mongo/writeconcerns.xml
View file

@ -36,11 +36,23 @@
</para>
</warning>
<para>
When using acknowledged writes and the ReplicaSet has failedover, 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,
there will be no way for the driver to know about the change so it will
continuously and silently fail to write.
</para>
<para>
The default Write Concern for the <classname>MongoClient</classname> is
<literal>1</literal>, acknowledge.
</para>
<para>
<table xml:id="mongo.writeconcerns.options">
<title>Available Write Concerns</title>
@ -246,6 +258,15 @@ try {
</para>
</simplesect>
<simplesect role="seealso">
&reftitle.seealso;
<simplelist>
<member>
<link xlink:href="&url.mongodb.docs;applications/replication/#replica-set-write-concern">MongoDB WriteConcern docs</link>
</member>
</simplelist>
</simplesect>
<simplesect role="changelog">
&reftitle.changelog;
<informaltable>