[prev in list] [next in list] [prev in thread] [next in thread]
List: php-doc-cvs
Subject: [DOC-CVS] svn: /phpdoc/en/trunk/reference/mongo/ book.xml datatypes.xml mongocollection/update.xml m
From: Kristina_Chodorow <kristina () php ! net>
Date: 2009-11-25 15:34:18
Message-ID: svn-kristina-1259163258-291315-1008721190 () svn ! php ! net
[Download RAW message or body]
kristina Wed, 25 Nov 2009 15:34:18 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=291315
Log:
manual: tutorial, types, ru of crud
Changed paths:
U phpdoc/en/trunk/reference/mongo/book.xml
U phpdoc/en/trunk/reference/mongo/datatypes.xml
U phpdoc/en/trunk/reference/mongo/mongocollection/update.xml
U phpdoc/en/trunk/reference/mongo/mongotimestamp.xml
A phpdoc/en/trunk/reference/mongo/queries.xml
A phpdoc/en/trunk/reference/mongo/tutorial.xml
A phpdoc/en/trunk/reference/mongo/updates.xml
["svn-diffs-291315.txt" (text/x-diff)]
Modified: phpdoc/en/trunk/reference/mongo/book.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/book.xml 2009-11-25 15:22:02 UTC (rev 291314)
+++ phpdoc/en/trunk/reference/mongo/book.xml 2009-11-25 15:34:18 UTC (rev 291315)
@@ -21,7 +21,11 @@
&reference.mongo.setup;
&reference.mongo.examples;
+
+ &reference.mongo.tutorial;
&reference.mongo.datatypes;
+ &reference.mongo.queries;
+ &reference.mongo.updates;
&reference.mongo.reference;
Modified: phpdoc/en/trunk/reference/mongo/datatypes.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/datatypes.xml 2009-11-25 15:22:02 UTC (rev \
291314)
+++ phpdoc/en/trunk/reference/mongo/datatypes.xml 2009-11-25 15:34:18 UTC (rev \
291315) @@ -3,64 +3,106 @@
<chapter xml:id="mongo.datatypes" xmlns="http://docbook.org/ns/docbook" \
xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Data Types</title>
<para>
- MongoDB supports the following built-in PHP types:
+ MongoDB allows programmers to save and query for data expressed in all of the
+ basic PHP types, compound types (arrays, associative arrays, and objects), and
+ a half-dozen classes provided by the MongoDB PHP driver (for regular
+ expressions, dates, and other specialized applications).
</para>
- <itemizedlist>
- <listitem>
- <para>
- &null;
- </para>
- <para>
- Fairly self-explanatory.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>boolean</literal>
- </para>
- <para>
- &true; and &false;.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>int</literal>
- </para>
- <para>
- 4-byte integers.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>float</literal>
- </para>
- <para>
- 8-byte doubles.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>string</literal>
- </para>
- <para>
- UTF-8 strings.
- </para>
- </listitem>
- </itemizedlist>
-
<para>
- Arrays and objects can also be saved to the database. An array with ascending
- numeric keys will be saved as a an array, anything else will be saved as an
- object.
+ MongoDB uses a storage format called "BSON," Binary Serializable Object
+ Notation, which is similar to JSON but more compact and rich in types. Listed
+ below is the exact byte size of each type (or information required to compute
+ its size, in the case of variable-length types). Keep in mind that these
+ sizes do not include field names. The size of an object can be manually
+ computed, but it may be easier for programmers to call the
+ <function>bson_encode</function> function and take the length of the resulting
+ string.
</para>
+ <para>
+ An example of manually computing BSON size for saving the object
+ array("x" => null, "y" => 40):
+ <programlisting>
+<![CDATA[
+4 bytes (object size)
- <programlisting role="php">
-<![CDATA[
+1 byte (type of "x" field)
+2 bytes ("x" and "\0")
+0 bytes (for null)
+
+1 byte (type of "y" field)
+2 bytes ("y" and "\0")
+4 bytes (for an integer)
+
+1 byte (end-of-object byte)
+-----------------------
+15 bytes
+]]>
+ </programlisting>
+ </para>
+
+ <section>
+ <title>Simple Types</title>
+ <para>
+ The built-in types are:
+ </para>
+ <para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ <entry>Size in MongoDB (bytes)</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>&null;</entry>
+ <entry>Fairly self-explanatory.</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>boolean</entry>
+ <entry>&true; and &false;</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>Integer values.</entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>float</entry>
+ <entry>Double values.</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>string</entry>
+ <entry>Strings of UTF-8 characters.</entry>
+ <entry>string length + 1</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </section>
+
+ <section>
+ <title>Arrays and Objects</title>
+
+ <para>
+ Arrays and objects can also be saved to the database. An array with ascending
+ numeric keys will be saved as a an array, anything else will be saved as an
+ object.
+ </para>
+
+ <programlisting role="php">
+ <![CDATA[
<?php
-// $scores will be saved as an array
-$scores = array(98, 100, 73, 85);
-$collection->insert(array("scores" => $scores);
+ // $scores will be saved as an array
+ $scores = array(98, 100, 73, 85);
+ $collection->insert(array("scores" => $scores);
// $scores will be saved as an object
$scores = array("quiz1" => 98, "midterm" => 100, "quiz2" => 73, "final" => 85);
@@ -68,38 +110,38 @@
?>
]]>
- </programlisting>
+ </programlisting>
- <para>
- If you query for these objects using the database shell, they will look like:
- <programlisting>
-<![CDATA[
+ <para>
+ If you query for these objects using the database shell, they will look like:
+ <programlisting>
+ <![CDATA[
> db.students.find()
{ "_id" : ObjectId("4b06beada9ad6390dab17c43"), "scores" : [ 98, 100, 73, 85 ] }
{ "_id" : ObjectId("4b06bebea9ad6390dab17c44"), "scores" : { "quiz1" : 98, "midterm" \
: 100, "quiz2" : 73, "final" : 85 } } ]]>
- </programlisting>
- </para>
+ </programlisting>
+ </para>
- <para>
- The database can also save arbitrary PHP objects (although they will be
- returned as associative arrays). The fields are used for the key/value
- pairs. For example, a blog post might look like:
- <programlisting role="php">
-<![CDATA[
+ <para>
+ The database can also save arbitrary PHP objects (although they will be
+ returned as associative arrays). The fields are used for the key/value
+ pairs. For example, a blog post might look like:
+ <programlisting role="php">
+ <![CDATA[
<?php
-// the blog post class
-class Post {
+ // the blog post class
+ class Post {
- var $author;
- var $content;
- var $comments = array();
- var $date;
+ var $author;
+ var $content;
+ var $comments = array();
+ var $date;
- public function __construct($author, $content) {
- $this->author = $author;
- $this->content = $content;
+ public function __construct($author, $content) {
+ $this->author = $author;
+$this->content = $content;
$this->date = new MongoDate();
}
@@ -127,81 +169,153 @@
?>
]]>
- </programlisting>
- </para>
+ </programlisting>
+ </para>
- <para>
- From the database shell, this will look something like:
- <programlisting>
-<![CDATA[
+ <para>
+ From the database shell, this will look something like:
+ <programlisting>
+ <![CDATA[
> db.blog.find()
{ "_id" : ObjectId("4b06c263edb87a281e09dad8"), "author" : "Adam", "content" : "This \
is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:22:59 GMT-0500 (EST)" \
} { "_id" : ObjectId("4b06c282edb87a281e09dad9"), "author" : { "name" : "Fred", \
"karma" : 42 }, "content" : "This is a blog post", "comments" : [ ], "date" : "Fri \
Nov 20 2009 11:23:30 GMT-0500 (EST)", "title" : "Second Post" } ]]>
- </programlisting>
- </para>
+ </programlisting>
+ </para>
+ </section>
- <para>
- The Mongo PHP driver also defines a few new types to use with the database:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <classname>MongoId</classname>
- </para>
- <para>
- Unique document id.
- </para>
- </listitem>
- <listitem>
- <para>
- <classname>MongoDate</classname>
- </para>
- <para>
- Dates and times.
- </para>
- </listitem>
- <listitem>
- <para>
- <classname>MongoRegex</classname>
- </para>
- <para>
- Regular expressions.
- </para>
- </listitem>
- <listitem>
- <para>
- <classname>MongoCode</classname>
- </para>
- <para>
- JavaScript code.
- </para>
- </listitem>
- <listitem>
- <para>
- <classname>MongoBinData</classname>
- </para>
- <para>
- Binary data.
- </para>
- </listitem>
- <listitem>
- <para>
- <classname>MongoMinKey</classname>
- </para>
- <para>
- Always smaller than any other value.
- </para>
- </listitem>
- <listitem>
- <para>
- <classname>MongoMaxKey</classname>
- </para>
- <para>
- Always larger than any other value.
- </para>
- </listitem>
- </itemizedlist>
+ <section>
+ <title>MongoDB Types</title>
+
+ <para>
+ The Mongo PHP driver also defines a few new types to use with the database.
+ See class documentation for details and examples.
+ </para>
+ <para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ <entry>Size in MongoDB (bytes)</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><classname>MongoBinData</classname></entry>
+ <entry>Binary data.</entry>
+ <entry>Number of bytes in binary data + 5</entry>
+ </row>
+ <row>
+ <entry><classname>MongoCode</classname></entry>
+ <entry>JavaScript code.</entry>
+ <entry>String length of code + object size of scope.</entry>
+ </row>
+ <row>
+ <entry><classname>MongoDate</classname></entry>
+ <entry>Dates and times. Stored as milliseconds since the epoch.</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry><classname>MongoId</classname></entry>
+ <entry>Unique document id:
+ <itemizedlist>
+ <listitem>
+ <para>4 bytes of timestamp</para>
+ <para>
+ No two records can have the same id if they were inserted at different
+ times.
+ </para>
+ </listitem>
+ <listitem>
+ <para>3 bytes machine id</para>
+ <para>
+ No two records can have the same id if they were inserted on different
+ machines
+ </para>
+ </listitem>
+ <listitem>
+ <para>2 bytes thread id</para>
+ <para>
+ No two records can have the same id if they were inserted by different
+ threads running on the same machine.
+ </para>
+ </listitem>
+ <listitem>
+ <para>3 bytes incrementing value</para>
+ <para>
+ Each time an id is created, a global counter is incremented and used
+ as the increment value of the next id.
+ </para>
+ </listitem>
+ </itemizedlist>
+ Thus, no two records can have the same id unless a single process on a
+ single machine managed to insert 256^3 (over 16 million) documents in
+ one second, overflowing the increment field.
+ </entry>
+ <entry>12</entry>
+ </row>
+ <row>
+ <entry><classname>MongoMinKey</classname></entry>
+ <entry>Always smaller than any other value.</entry>
+ <entry>String length of code + object size of scope.</entry>
+ </row>
+ <row>
+ <entry><classname>MongoMaxKey</classname></entry>
+ <entry>JavaScript code.</entry>
+ <entry>Always larger than any other value.</entry>
+ </row>
+ <row>
+ <entry><classname>MongoRegex</classname></entry>
+ <entry>Regular expressions.</entry>
+ <entry>
+ Number of characters in regular expression + number of flags
+ </entry>
+ </row>
+ <row>
+ <entry><classname>MongoTimestamp</classname></entry>
+ <entry>Sharding timestamp</entry>
+ <entry>8</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </section>
+
+ <section>
+ <title>Unsupported Types</title>
+
+ <para>Types supported by Mongo, but not the PHP driver:</para>
+ <para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ <entry>Size in MongoDB (bytes)</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>long</entry>
+ <entry>
+ As PHP does not support 8 byte integers, longs fetched from the database
+ are converted to doubles. Integers will always be saved to the database
+ as 4 byte ints (even on machines that support 8 byte ints) and doubles
+ will be saved as 8 bytes doubles, so there is no way to save a long to
+ the database with the PHP driver.
+ </entry>
+ <entry>8</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </section>
+
</chapter>
<!-- Keep this comment at the end of the file
Modified: phpdoc/en/trunk/reference/mongo/mongocollection/update.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocollection/update.xml 2009-11-25 15:22:02 \
UTC (rev 291314)
+++ phpdoc/en/trunk/reference/mongo/mongocollection/update.xml 2009-11-25 15:34:18 \
UTC (rev 291315) @@ -81,6 +81,30 @@
Returns if the update was successfully sent to the database.
</para>
</refsect1>
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>1.0.1</entry>
+ <entry>
+ Changed "options" parameter from boolean to array. Pre-1.0.1, the
+ second parameter was an optional boolean value specifying an upsert.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
@@ -129,7 +153,7 @@
<?php
$c->drop();
-$c->update(array("uri" => "/summer_pics"), array("page hits" => array('$inc' => 1)), \
array("upsert" => true)); +$c->update(array("uri" => "/summer_pics"), array('$inc' => \
array("page hits" => 1)), array("upsert" => true)); var_dump($c->findOne());
?>
Modified: phpdoc/en/trunk/reference/mongo/mongotimestamp.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongotimestamp.xml 2009-11-25 15:22:02 UTC (rev \
291314)
+++ phpdoc/en/trunk/reference/mongo/mongotimestamp.xml 2009-11-25 15:34:18 UTC (rev \
291315) @@ -8,7 +8,7 @@
<partintro>
-<!-- {{{ MongoBinData intro -->
+<!-- {{{ MongoTimestamp intro -->
<section xml:id="mongotimestamp.intro">
&reftitle.intro;
<para>
Added: phpdoc/en/trunk/reference/mongo/queries.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/queries.xml (rev 0)
+++ phpdoc/en/trunk/reference/mongo/queries.xml 2009-11-25 15:34:18 UTC (rev 291315)
@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<chapter xml:id="mongo.queries" xmlns="http://docbook.org/ns/docbook" \
xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Querying MongoDB</title>
+
+ <section>
+ <title>Querying by _id</title>
+ <para>
+ Every object inserted is automatically assigned a unique _id field, which is
+ often a useful field to use in queries.
+ </para>
+ <para>
+ Suppose that we wish to find the document we just inserted. Inserting adds
+ and _id field to the document, so we can query by that:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$person = array("name" => "joe");
+
+$people->insert($person);
+
+// now $joe has an _id field
+$joe = $people->findOne(array("_id" => $person['_id']));
+
+?>
+]]>
+ </programlisting>
+ </para>
+ <para>
+ Unless the user has specified otherwise, the _id field is a
+ <classname>MongoId</classname>. The most common mistake is attepting to use
+ a string to match a <classname>MongoId</classname>. Keep in mind that these
+ are two different datatypes, and will not match each other in the same way
+ that the string "array()" is not the same as an empty array. For example:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$person = array("name" => "joe");
+
+$people->insert($person);
+
+// convert the _id to a string
+$pid = $person['_id'] . "";
+
+// FAILS - $pid is a string, not a MongoId
+$joe = $people->findOne(array("_id" => $pid));
+
+?>
+]]>
+ </programlisting>
+ </para>
+ </section>
+
+ <section>
+ <title>Arrays</title>
+
+ <para>
+ Suppose that we wish to find all documents with an array element of a given
+ value. For example, documents with a "gold" award, such as:
+
+ <programlisting>
+<![CDATA[
+{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "awards" : ["gold", "silver", \
"bronze"]} +]]>
+ </programlisting>
+
+ This can be done with a simple query, ignoring the fact that "awards" is an
+ array:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+ $cursor = $collection->find(array("awards" => "gold"));
+
+?>
+]]>
+ </programlisting>
+ </para>
+
+ <para>
+ Suppose we are querying for a more complex object, if each element of the
+ array were an object itself, such as:
+
+ <programlisting>
+<![CDATA[
+{
+ "_id" : ObjectId("4b06c282edb87a281e09dad9"),
+ "awards" :
+ [
+ {
+ "first place" : "gold"
+ },
+ {
+ "second place" : "silver"
+ },
+ {
+ "third place" : "bronze"
+ }
+ ]
+}
+]]>
+ </programlisting>
+
+ Still ignoring that this is an array, we can use dot notation to query the
+ subobject:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+ $cursor = $collection->find(array("awards.first place" => "gold"));
+
+?>
+]]>
+ </programlisting>
+
+ Notice that it doesn't matter that there is a space in the the field name
+ (although it may be best not to use spaces, just to make things more
+ readable).
+ </para>
+ </section>
+
+</chapter>
Added: phpdoc/en/trunk/reference/mongo/tutorial.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/tutorial.xml (rev 0)
+++ phpdoc/en/trunk/reference/mongo/tutorial.xml 2009-11-25 15:34:18 UTC (rev 291315)
@@ -0,0 +1,402 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<chapter xml:id="mongo.tutorial" xmlns="http://docbook.org/ns/docbook" \
xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Tutorial</title>
+ <section>
+ <title>Making a Connection</title>
+ <para>
+ To connect to the database server, use one of the following:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$connection = new Mongo(); // connects to localhost:27017
+$connection = new Mongo( "example.com" ); // connect to a remote host (default port)
+$connection = new Mongo( "example.com:65432" ); // connect to a remote host at a \
given port +
+?>
+]]>
+ </programlisting>
+
+ Now $connection can be used to get a database.
+ </para>
+ </section>
+
+ <section>
+ <title>Getting a Database</title>
+ <para>
+ To select a database, use:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$db = $connection->selectDB( "dbname" );
+
+?>
+]]>
+ </programlisting>
+ The database does not need to be created in advance, you can create new
+ databases by selecting them. Be careful of typos! You can inadvertently
+ create a new database, which can cause confusing errors:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$db = $connection->selectDB( "mybiglongdbname" );
+// do some stuff
+$db = $connection->selectDB( "mybiglongdbnme" );
+// now connected to a different database!
+
+]]>
+ </programlisting>
+ </para>
+ </section>
+
+ <section>
+ <title>Getting A Collection</title>
+ <para>
+ To get a specific collection, use
+ <function>MongoDB::selectCollection</function>. Similarly to
+ <function>MongoDB::selectDB</function>, this creates the collection if it
+ does not already exist.
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$collection = $db->selectCollection( "foobar" );
+
+?>
+]]>
+ </programlisting>
+ </para>
+ </section>
+
+ <section>
+ <title>Inserting a Document</title>
+ <para>
+ Associative arrays are the basic object that can be saved to a collection in
+ the database. A somewhat random "document" might be:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$doc = array( "name" => "MongoDB",
+ "type" => "database",
+ "count" => 1,
+ "info" => (object)array( "x" => 203,
+ "y" => 102),
+ "versions" => array("0.9.7", "0.9.8", "0.9.9")
+);
+
+?>
+]]>
+ </programlisting>
+
+ Note that you can have nested arrays and objects. Objects and documents are
+ almost synonymous in MongoDB: you could call $doc a document or an object,
+ but the "info" field is always an object, never a document. This convention
+ is used for all of the documentation.
+ </para>
+ <para>
+ To insert this document, use <function>MongoCollection::insert</function>:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$m = new Mongo();
+$collection = $m->selectDB( "foo" )->selectCollection( "bar" );
+$collection->insert( $doc );
+
+?>
+]]>
+ </programlisting>
+ </para>
+ </section>
+
+ <section>
+ <title>
+ Finding Documents using <function>MongoCollection::findOne</function>
+ </title>
+ <para>
+ To show that the document we inserted in the previous step is there, we can
+ do a simple findOne() operation to get the first document in the collection.
+ This method returns a single document (rather than the
+ <classname>MongoCursor</classname> that
+ <function>MongoCollection::find</function> returns), and it's useful for
+ things where there only is one document matching the query or you are only
+ interested in one result.
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$obj = $collection->findOne();
+var_dump( $obj );
+
+?>
+]]>
+ </programlisting>
+
+ and you should see
+
+ <programlisting>
+<![CDATA[
+array(5) {
+ ["_id"]=>
+ object(MongoId)#6 (0) {
+ }
+ ["name"]
+ string(7) "MongoDB"
+ ["type"]=>
+ string(8) "database"
+ ["count"]=>
+ int(1)
+ ["info"]=>
+ array (2) {
+ ["x"]=>
+ int(203)
+ ["y"]=>
+ int(102)
+ }
+ ["versions"]
+ array(3) {
+ [0]=>
+ string(5) "0.9.7"
+ [1]=>
+ string(5) "0.9.8"
+ [2]=>
+ string(5) "0.9.9"
+ }
+}
+]]>
+ </programlisting>
+ </para>
+ <para>
+ Note the _id field has been added automatically to your document. MongoDB
+ reserves element names that start with _ and $ for internal use.
+ </para>
+ </section>
+
+ <section>
+ <title>Adding Multiple Documents</title>
+ <para>
+ In order to do more interesting things with queries, let's add multiple
+ simple documents to the collection. These documents will just be
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+array( "i" => value );
+
+?>
+]]>
+ </programlisting>
+
+ and we can do this fairly efficiently in a loop
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+for($i=0; $i<100; $i++) {
+ $collection->insert( array( "i" => $i ) );
+}
+
+?>
+]]>
+ </programlisting>
+ </para>
+
+ <para>
+ Notice that we can insert arrays with different key sets into the same
+ collection. This aspect is what we mean when we say that MongoDB is
+ "schema-free".
+ </para>
+ </section>
+
+ <section>
+ <title>Counting Documents in A Collection</title>
+ <para>
+ Now that we've inserted 101 documents (the 100 we did in the loop, plus the
+ first one), we can check to see if we have them all using the count() method.
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+echo $collection->count();
+
+?>
+]]>
+ </programlisting>
+ and it should print 101.
+ </para>
+ <para>
+ <function>MongoCollection::count</function> can take query and field
+ arguments, as well. You can also do a count on a
+ <classname>MongoCursor</classname> (see below), which will take into account
+ any filters you have placed on your query.
+ </para>
+ </section>
+
+ <section>
+ <title>Using a Cursor to Get All the Documents</title>
+ <para>
+ In order to get all the documents in the collection, we will use
+ <function>MongoCollection::find</function>. The find() method returns a
+ <classname>MongoCursor</classname> object which allows us to iterate over the
+ set of documents that matched our query. So to query all of the documents and
+ print them out:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$cursor = $collection->find();
+foreach ($cursor as $id => $value) {
+ echo "$id: ";
+ var_dump( $value );
+}
+
+?>
+]]>
+ </programlisting>
+
+ and that should print all 101 documents in the collection. $id is the _id
+ field of a document, and $value is the document itself.
+ </para>
+ </section>
+
+ <section>
+ <title>Setting Criteria for a Query</title>
+ <para>
+ We can create a query to pass to the find() method to get a subset of the
+ documents in our collection. For example, if we wanted to find the document
+ for which the value of the "i" field is 71, we would do the following:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$query = array( "i" => 71 );
+$cursor = $collection->find( $query );
+
+while( $cursor->hasNext() ) {
+ var_dump( $cursor->getNext() );
+}
+
+?>
+]]>
+ </programlisting>
+
+ and it should just print just one document
+
+ <programlisting>
+<![CDATA[
+array(2) {
+ ["_id"]=>
+ object(MongoId)#6 (0) {
+ }
+ ["i"]=>
+ int(71)
+ ["_ns"]=>
+ "testCollection"
+}
+]]>
+ </programlisting>
+ </para>
+ </section>
+
+ <section>
+ <title>Getting A Set of Documents With a Query</title>
+ <para>
+ We can use the query to get a set of documents from our collection. For
+ example, if we wanted to get all documents where "i" > 50, we could write:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$query = array( "i" => array( '$gt' => 50 ) ); //note the single quotes around '$gt'
+$cursor = $coll->find( $query );
+
+while( $cursor->hasNext() ) {
+ var_dump( $cursor->getNext() );
+}
+
+?>
+]]>
+ </programlisting>
+
+ which should print the documents where i > 50. We could also get a range, say
+ 20 < i <= 30:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$query = array( "i" => array( "\$gt" => 20, "\$lte" => 30 ) );
+$cursor = $coll->find( $query );
+
+while( $cursor->hasNext() ) {
+ var_dump( $cursor->getNext() );
+}
+
+?>
+]]>
+ </programlisting>
+
+ As it is easy to forget to escape the "$", you can also choose your own
+ special character to use instead of '$'. Choose a character that will not
+ occur in your key names, e.g. ":", and add the following line to php.ini:
+
+ <programlisting>
+<![CDATA[
+mongo.cmd = ":"
+]]>
+ </programlisting>
+
+ Then the example above would look like:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$query = array( "i" => array( ":gt" => 20, ":lte" => 30 ) );
+
+?>
+]]>
+ </programlisting>
+
+ You can also change it in your code using ini_set("mongo.cmd", ":"). Of
+ course, you can also just use single quotes around the $.
+ </para>
+ </section>
+
+ <section>
+ <title>Creating An Index</title>
+ <para>
+ MongoDB supports indexes, and they are very easy to add on a collection. To
+ create an index, you just specify the field that should be indexed, and
+ specify if you want the index to be ascending (1) or descending (-1). The
+ following creates an ascending index on the "i" field :
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$coll->ensureIndex( array( "i" => 1 ) ); // create index on "i"
+$coll->ensureIndex( array( "i" => -1, "j" => 1 ) ); // index on "i" descending, "j" \
ascending +
+?>
+]]>
+ </programlisting>
+ </para>
+ </section>
+</chapter>
Added: phpdoc/en/trunk/reference/mongo/updates.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/updates.xml (rev 0)
+++ phpdoc/en/trunk/reference/mongo/updates.xml 2009-11-25 15:34:18 UTC (rev 291315)
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<chapter xml:id="mongo.updates" xmlns="http://docbook.org/ns/docbook" \
xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Updates</title>
+
+ <para>
+ Updates can be one of the the most complicated operation available with
+ MongoDB. They combine a query with an action, modifying documents that match
+ the criteria. They are also extremely powerful, allowing you to change
+ documents quickly and replace them altogether. They are done in-place (when
+ possible) with little overhead.
+ </para>
+
+ <section>
+ <title>Updating Nested Objects</title>
+
+ <para>
+ Suppose we wish to change the name of a comment's author in this document:
+
+ <programlisting>
+<![CDATA[
+{
+ "_id" : ObjectId("4b06c282edb87a281e09dad9"),
+ "content" : "this is a blog post.",
+ "comments" :
+ [
+ {
+ "author" : "Mike",
+ "comment" : "I think that blah blah blah...",
+ },
+ {
+ "author" : "John",
+ "comment" : "I disagree."
+ }
+ ]
+}
+]]>
+ </programlisting>
+
+ In order to change an inner field, we use $set (so that all of the other
+ fields are not removed!) with the index of comment to change:
+
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$blog->update($criteria, array('$set' => array("comments.1" => array("author" => \
"Jim")))); +
+?>
+]]>
+ </programlisting>
+ </para>
+ </section>
+</chapter>
--
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic