svn: /phpdoc/en/trunk/reference/mongo/ book.xml mongocollection/update.xml mongocursor.xml

kristina Thu, 19 Nov 2009 21:09:52 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=291033 Log: update parameters, cursor description Changed paths: U phpdoc/en/trunk/reference/mongo/book.xml U phpdoc/en/trunk/reference/mongo/mongocollection/update.xml U phpdoc/en/trunk/reference/mongo/mongocursor.xml Modified: phpdoc/en/trunk/reference/mongo/book.xml =================================================================== --- phpdoc/en/trunk/reference/mongo/book.xml 2009-11-19 21:09:21 UTC (rev 291032) +++ phpdoc/en/trunk/reference/mongo/book.xml 2009-11-19 21:09:52 UTC (rev 291033) @@ -8,24 +8,15 @@ <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;. + More information and downloads for Mongo can be found at &url.mongodb; and + information about PHP in particular at &url.mongodb.php;. </para> - <para> - There are also tutorials at &url.mongodb.php;. - </para> - </preface> &reference.mongo.setup; Modified: phpdoc/en/trunk/reference/mongo/mongocollection/update.xml =================================================================== --- phpdoc/en/trunk/reference/mongo/mongocollection/update.xml 2009-11-19 21:09:21 UTC (rev 291032) +++ phpdoc/en/trunk/reference/mongo/mongocollection/update.xml 2009-11-19 21:09:52 UTC (rev 291033) @@ -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 @@ ]]> </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 Modified: phpdoc/en/trunk/reference/mongo/mongocursor.xml =================================================================== --- phpdoc/en/trunk/reference/mongo/mongocursor.xml 2009-11-19 21:09:21 UTC (rev 291032) +++ phpdoc/en/trunk/reference/mongo/mongocursor.xml 2009-11-19 21:09:52 UTC (rev 291033) @@ -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 @@ $cursor->skip(4); ?> ]]> + </programlisting> </para> </section> <!-- }}} -->