safe insert

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

reference/mongo/mongocollection/insert.xml

@@ -53,6 +53,13 @@
   </para>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws MongoCursorException if <parameter>safe</parameter> is set and the insert fails. (Version 1.0.1+)
+  </para>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
@@ -93,6 +100,34 @@ array(1) {
 ]]>
    </screen>
   </example>
+
+  <example>
+   <title><function>MongoCollection::insert</function> safe 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.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$person = array("name" => "Joe", "age" => 20);
+$collection->insert($person, true);
+
+// now $person has an _id field, so if we save it 
+// again, we will get an exception
+try {
+    $collection->insert($person, true);
+}
+catch(MongoCursorException $e) {
+    echo "Can't save the same person twice!\n";
+}
+
+?>
+]]>
+   </programlisting>
+  </example>
  </refsect1>
 
 </refentry>