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

kristina Fri, 12 Nov 2010 04:06:19 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=305288 Log: added examples of different types of updates/upserts Changed paths: U phpdoc/en/trunk/reference/mongo/mongocollection/update.xml U phpdoc/en/trunk/reference/mongo/updates.xml Modified: phpdoc/en/trunk/reference/mongo/mongocollection/update.xml =================================================================== --- phpdoc/en/trunk/reference/mongo/mongocollection/update.xml 2010-11-12 00:30:35 UTC (rev 305287) +++ phpdoc/en/trunk/reference/mongo/mongocollection/update.xml 2010-11-12 04:06:19 UTC (rev 305288) @@ -254,6 +254,37 @@ } ]]> </screen> + <para> + If <literal>newobj</literal> does not contain $-operators, an upsert will + create a new document from it alone. This matches the behavior of a normal + update, where not using $-operators causes the whole document to be + overwritten. + </para> + <programlisting role="php"> +<![CDATA[ +<?php + +$c->update(array("name" => "joe"), array("username" => "joe312", "createdAt" => new MongoDate()), + array("upsert" => true)); + +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +array(3) { + ["_id"]=> + object(MongoId)#10 (0) { + } + ["username"]=> + string(6) "joe312" + ["createdAt"]=> + object(MongoDate)#4 (0) { + } +} +]]> + </screen> </example> <example> <title><function>MongoCollection::update</function> multiple example</title> @@ -282,7 +313,8 @@ <refsect1 role="seealso"> &reftitle.seealso; <para> - MongoDB core docs on <link xlink:href="&url.mongodb.dochub.update;">update</link>. + The <link xlink:href="mongo.updates">PHP documentation on updates</link> and the + <link xlink:href="&url.mongodb.dochub.update;">MongoDB core docs</link>. </para> </refsect1> Modified: phpdoc/en/trunk/reference/mongo/updates.xml =================================================================== --- phpdoc/en/trunk/reference/mongo/updates.xml 2010-11-12 00:30:35 UTC (rev 305287) +++ phpdoc/en/trunk/reference/mongo/updates.xml 2010-11-12 04:06:19 UTC (rev 305288) @@ -13,6 +13,71 @@ </para> <section> + <title>Modifying vs. replacing documents</title> + + <para> + There are two types of updates you can use: modifying updates and replacing + updates. Modifying updates contain $-operators and change fields in a + document: they might increment counters, push new elements onto an array, + or change the type of a field. + </para> + + <para> + For example, a modifying update could add a new field to a document. + <programlisting role="php"> +<![CDATA[ + +/** suppose documents look like: + * {"username" : "...", "password" : "...", "email" : "..."} + */ +$coll->update(array("username" => "joe"), array('$set' => array("twitter" => "@joe4153"))); + +/** now the document will look like: + * {"username" : "joe", "password" : "...", "email" : "...", "twitter" : "@joe4153"} + */ + +]]> + </programlisting> + </para> + + <para> + Replacing updates replace the entire matching document with a new document. + They are generally not as efficient as using $-modifiers, but can be very + usefully for complex operations or updates that can't be expressed in terms + of $-operators. + </para> + + <para> + For example, a replacing update can completely change the structure of a + document. + <programlisting role="php"> +<![CDATA[ + +/** suppose documents look like: + * {"username" : "...", "password" : "...", "email" : "..."} + */ +$coll->update(array("username" => "joe"), array("userId" => 12345, "info" => array( + "name" => "joe", "twitter" => "@joe4153", "email" => "..."), "likes" => array())); + +/** now the document will look like: + * { + * "userId" : 12345, + * "info" : { + * "name" : "joe", + * "twitter" : "@joe4153", + * "email" : "..." + * }, + * "likes" : [] + * } + */ + +]]> + </programlisting> + </para> + + </section> + + <section> <title>Updating Nested Objects</title> <para>