More WriteConcern updates

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328544 c90b9560-bf6c-de11-be94-00142212c4b1

reference/mongo/mongocollection/batchinsert.xml

@@ -67,20 +67,21 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;  
   <para>
-   If "safe" is set, returns an associative array with the status of the inserts
-   ("ok") and any error that may have occured ("err").  Otherwise, returns 
-   &true; if the batch insert was successfully sent, &false; otherwise.
+   If the <literal>w</literal> parameter is set to acknowledge the write,
+   returns an associative array with the status of the inserts ("ok") and any
+   error that may have occured ("err").  Otherwise, returns &true; if the
+   batch insert was successfully sent, &false; otherwise.
   </para>
  </refsect1>
 
  <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>
   <para>
-   Throws <classname>MongoCursorTimeoutException</classname> if the "safe" 
+   Throws <classname>MongoCursorTimeoutException</classname> if the "w" 
    option is set to a value greater than one and the database cannot replicate 
    the operation in <literal>MongoCollection::$wtimeout</literal> milliseconds.
   </para>

reference/mongo/mongocollection/distinct.xml

@@ -106,7 +106,7 @@ array(2) {
 <?php
 $c->insert(array("user" => array("points" => 25)));
 $c->insert(array("user" => array("points" => 31)));
-$c->insert(array("user" => array("points" => 25)), array("safe" => true));
+$c->insert(array("user" => array("points" => 25)));
 
 $retval = $c->distinct("user.points");
 var_dump($retval);

reference/mongo/mongocollection/ensureindex.xml

@@ -216,11 +216,11 @@
    128 bytes. (Version 1.0.11+)
   </para>
   <para>
-   Throws <classname>MongoCursorException</classname> if the "safe" option is 
+   Throws <classname>MongoCursorException</classname> if the "w" option is 
    set and the index creation fails.
   </para>
   <para>
-   Throws <classname>MongoCursorTimeoutException</classname> if the "safe" 
+   Throws <classname>MongoCursorTimeoutException</classname> if the "w" 
    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.

reference/mongo/mongocollection/save.xml

@@ -57,7 +57,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   If <parameter>safe</parameter> was set, returns an array containing the status of the save.
+   If <parameter>w</parameter> was set, returns an array containing the status of the save.
    Otherwise, returns a boolean representing if the array was not empty (an empty array will not 
    be inserted).
   </para>
@@ -66,11 +66,11 @@
  <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 save fails.
   </para>
   <para>
-   Throws <classname>MongoCursorTimeoutException</classname> if the "safe" 
+   Throws <classname>MongoCursorTimeoutException</classname> if the "w" 
    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.

reference/mongo/tutorial.xml

@@ -291,26 +291,24 @@ array(6) {
 <![CDATA[
 <?php
 
-$db->foo->insert(array("_id" => 1), array("w" => 1));
+$db->foo->insert(array("_id" => 1));
 // this will throw an exception
-$db->foo->insert(array("_id" => 1), array("w" => 1));
+$db->foo->insert(array("_id" => 1));
 
 // this is fine, as it is a different collection
-$db->bar->insert(array("_id" => 1), array("w" => 1));
+$db->bar->insert(array("_id" => 1));
 
 ?>
 ]]>
     </programlisting>
    </example>
    <para>
-    Note that these inserts pass a second array:
-    <literal>array("safe" => true)</literal>.  This second field specifies
-    options for the insert.  By default, the driver does not wait for a database
-    response for writes, so the driver would not catch the the
-    <literal>_id</literal>.  As we specify that this is a "safe" write, the
-    driver will wait for a database response and see that the write did not go
-    through.  In general, all writes should use the "safe" option (it is omitted
-    in previous examples for simplicity).
+    By default the driver will ensure the servers 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.
    </para>
    <section xml:id="mongo.tutorial.findone.seealso">
     <title>See Also</title>
@@ -322,11 +320,9 @@ $db->bar->insert(array("_id" => 1), array("w" => 1));
      <classname>MongoId</classname> goes into more detail on unique ids.
     </para>
     <para>
-     The <link linkend="mongo.writes">writes</link> section covers safe
-     writes in more depth, as do the writing functions such as
-     <function>MongoCollection::insert</function>,
-     <function>MongoCollection::update</function>, and
-     <function>MongoCollection::remove</function>.
+     The <link linkend="mongo.writes">writes</link> section covers
+     writes in more depth, and the <xref linkend="mongo.writeconcerns" />
+     chapter goes into details of the various Write Concern options.
     </para>
    </section>
   </section>

reference/mongo/writeconcerns.xml

@@ -117,9 +117,9 @@
    to a system collection).
   </para>
   <para>
-   While developing, you should always use safe writes (to protect against 
+   While developing, you should always use acknowledged writes (to protect against 
    inadvertent mistakes, such as syntax errors, invalid operators, duplicate key errors and so on).  In 
-   production, unsafe writes can be used for "unimportant" data.  Unimportant
+   production, unacknowledged writes can be used for "unimportant" data.  Unimportant
    data varies on application, but it's generally automatically (instead of user
    generated) data, such as click tracking or GPS locations, where you can get
    thousands of records per second.