From b56bee1a3159a2dc48e4ca37436ae99925656e2e Mon Sep 17 00:00:00 2001
From: Kristina Chodorow <kristina@php.net>
Date: Thu, 19 Nov 2009 21:09:52 +0000
Subject: [PATCH] update parameters, cursor description

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@291033 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongo/book.xml                   | 15 +---
 reference/mongo/mongocollection/update.xml | 81 +++++++++++++++++++++-
 reference/mongo/mongocursor.xml            | 22 +++++-
 3 files changed, 101 insertions(+), 17 deletions(-)

diff --git a/reference/mongo/book.xml b/reference/mongo/book.xml
index 50555ccee7..980f1d251d 100644
--- a/reference/mongo/book.xml
+++ b/reference/mongo/book.xml
@@ -7,23 +7,14 @@
 
  <preface xml:id="intro.mongo">
   &reftitle.intro;
-  <para>
-   These functions allow PHP to interact with Mongo database servers.
-  </para>
-
   <para>
    MongoDB is a high-performance, open source, schema-free document database 
-   designed for cloud computing. The project's goal is a cloud-scale data store 
-   that's easy to deploy, manage and use. It's network accessible and written in 
-   C++.
+   designed for creating scalable websites. 
   </para>
 
   <para>
-   More information and downloads for Mongo can be found at &url.mongodb;.
-  </para>
-
-  <para>
-   There are also tutorials at &url.mongodb.php;.
+   More information and downloads for Mongo can be found at &url.mongodb; and
+   information about PHP in particular at &url.mongodb.php;.
   </para>
 
  </preface>
diff --git a/reference/mongo/mongocollection/update.xml b/reference/mongo/mongocollection/update.xml
index 451df90d87..c69263afb2 100644
--- a/reference/mongo/mongocollection/update.xml
+++ b/reference/mongo/mongocollection/update.xml
@@ -13,7 +13,7 @@
    <modifier>public</modifier> <type>boolean</type><methodname>MongoCollection::update</methodname>
    <methodparam><type>array</type><parameter>criteria</parameter></methodparam>
    <methodparam><type>array</type><parameter>newobj</parameter></methodparam>
-   <methodparam choice="opt"><type>boolean</type><parameter>upsert</parameter><initializer>&false;</initializer></methodparam>
+   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
  </refsect1>
 
@@ -43,11 +43,32 @@
     </varlistentry>   
     <varlistentry>
      <term>
-      <parameter>upsert</parameter>
+      <parameter>options</parameter>
      </term>
      <listitem>
       <para>
-       If <literal>$newobj</literal> should be inserted if the criteria is not found.
+       This parameter is an associative array of the form 
+       <literal>array("optionname" => &lt;boolean&gt;, ...)</literal>. Currently 
+       supported options are: 
+       <itemizedlist>
+	<listitem>
+	 <para>
+	  <literal>"upsert"</literal>
+	 </para>
+	 <para>
+	  If no document matches $criteria, a new document will be created from 
+	  $criteria and $newobj (see upsert example below).
+	 </para>
+	</listitem>
+	<listitem>
+	 <para>
+	  <literal>"multiple"</literal>
+	 </para>
+	 <para>
+          All documents matching $criteria will be updated.
+	 </para>
+	</listitem>
+       </itemizedlist>
       </para>
      </listitem>
     </varlistentry>   
@@ -97,6 +118,60 @@ array(4) {
 ]]>
    </screen>
   </example>
+  <example>
+   <title><function>MongoCollection::update</function> upsert example</title>
+   <para>
+    Upserts can simplify code, as a single line can create the object if it does
+    not exist yet and update it if it does.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$c->drop();
+$c->update(array("uri" => "/summer_pics"), array("page hits" => array('$inc' => 1)), array("upsert" => true));
+var_dump($c->findOne());
+
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+array(3) {
+  ["_id"]=>
+  object(MongoId)#9 (0) {
+  }
+  ["uri"]=>
+  string(12) "/summer_pics"
+  ["page hits"]=>
+  int(1)
+}
+]]>
+   </screen>
+  </example>
+  <example>
+   <title><function>MongoCollection::update</function> multiple example</title>
+   <para>
+    By default, <function>MongoCollection::update</function> will only update
+    the first document matching $criteria that it finds.  Using the "multiple"
+    option can override this behavior, if needed.
+   </para>
+   <para>
+    This example adds a "gift" field to every person whose birthday is in the
+    next day.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$today = array('$gt' => new MongoDate(), '$lt' => new MongoDate(strtotime("+1 day")));
+$people->update("birthday" => $today), array('$set' => array('gift' => $surprise), array("multiple" => true));
+
+?>
+]]>
+   </programlisting>
+  </example>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/mongo/mongocursor.xml b/reference/mongo/mongocursor.xml
index 1ffcc19adb..75498656bb 100644
--- a/reference/mongo/mongocursor.xml
+++ b/reference/mongo/mongocursor.xml
@@ -15,8 +15,25 @@
     Result object for database query.
    </para>
    <para>
-    The database is not actually queried until next() or hasNext() is called.
-    Before the database is queried, commands can be strung together, as in:
+    A <classname>MongoCursor</classname> has two "life stages": pre- and post-
+    query.  A cursor can be created manually by calling the constructor, but it
+    is most often created by calling <function>MongoCollection::find</function>.
+    When a cursor is created, it has not yet contacted the database, so it is in
+    its pre-query state.  In this state, the client can further specify what
+    they want the query to do, including adding limits, skips, sorts, and more
+    advanced options.
+   </para>
+   <para>
+    When the client attempts to get a result (by calling 
+    <function>MongoCursor::next</function>, directly or indirectly), the cursor
+    moves into the post-query stage.  At this point, the query has been executed
+    by the database and cannot be modified anymore.  At this point, the only
+    functions available are the iterator functions, 
+    <function>MongoCursor::hasNext</function>, and 
+    <function>MongoCursor::getNext</function>.
+   </para>
+   <para>
+    <programlisting role="php">
 <![CDATA[
 <?php
 $cursor = $collection->find()->limit(10);
@@ -31,6 +48,7 @@ var_dump($cursor->getNext());
 $cursor->skip(4);
 ?>
 ]]>
+    </programlisting>
    </para>
   </section>
   <!-- }}} -->