From 59e9f400e0800d86ce02de1868d80433940ebd82 Mon Sep 17 00:00:00 2001
From: "Jonathan H. Wage" <jwage@php.net>
Date: Wed, 19 May 2010 19:33:11 +0000
Subject: [PATCH] Added dozens of new examples to the Mongo extension
 documentation.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@299506 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongo/mongo/listdbs.xml             | 44 +++++++++++-
 .../mongo/mongocollection/batchinsert.xml     | 37 ++++++----
 .../mongo/mongocollection/createdbref.xml     |  2 +-
 .../mongo/mongocollection/deleteindexes.xml   | 29 ++++++++
 reference/mongo/mongocollection/drop.xml      | 31 ++++++++
 reference/mongo/mongocollection/find.xml      | 37 ++++++++++
 reference/mongo/mongocollection/findone.xml   | 51 ++++++++++++++
 reference/mongo/mongocollection/getdbref.xml  | 12 +++-
 reference/mongo/mongodb/createdbref.xml       | 70 +++++++++++++++++++
 reference/mongo/mongodb/drop.xml              | 30 ++++++++
 reference/mongo/mongodb/getdbref.xml          | 26 +++++++
 reference/mongo/mongodb/getgridfs.xml         | 24 +++++++
 reference/mongo/mongodb/repair.xml            | 29 ++++++++
 reference/mongo/mongogridfs/findone.xml       | 62 ++++++++++++++++
 reference/mongo/mongogridfsfile/getbytes.xml  | 21 ++++++
 reference/mongo/mongogridfsfile/write.xml     | 18 +++++
 16 files changed, 507 insertions(+), 16 deletions(-)

diff --git a/reference/mongo/mongo/listdbs.xml b/reference/mongo/mongo/listdbs.xml
index 607a612bfb..4bb7bbf307 100644
--- a/reference/mongo/mongo/listdbs.xml
+++ b/reference/mongo/mongo/listdbs.xml
@@ -3,7 +3,7 @@
 <!-- $Revision$ -->
 <refentry xml:id="mongo.listdbs" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
-  <refname><function>Mongo::listDBs</function></refname>
+  <refname><methodname>Mongo::listDBs</methodname></refname>
   <refpurpose>Lists all of the databases available.</refpurpose>
  </refnamediv>
 
@@ -31,6 +31,48 @@
    if this method ran successfully.
   </para>
  </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><methodname>Mongo::listDBs</methodname> example</title>
+   <para>
+    Example demonstrating how to use listDBs and the returned data structure.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$mongo = new Mongo();
+$dbs = $mongo->listDBs();
+print_r($dbs);
+
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+Array
+(
+    [databases] => Array
+        (
+            [0] => Array
+                (
+                    [name] => doctrine
+                    [sizeOnDisk] => 218103808
+                    [empty] => 
+                )
+        )
+
+    [totalSize] => 218103808
+    [ok] => 1
+)
+
+]]>
+   </screen>
+  </example>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongocollection/batchinsert.xml b/reference/mongo/mongocollection/batchinsert.xml
index 5064047c91..4f3338a584 100644
--- a/reference/mongo/mongocollection/batchinsert.xml
+++ b/reference/mongo/mongocollection/batchinsert.xml
@@ -105,29 +105,40 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-$batch = array();
-for ($i=0; $i<100; $i++) {
-  $batch[] = array("i" => i);
+
+$users = array();
+for ($i = 0; $i<100; $i++) {
+  $users[] = array('username' => 'user'.$i, 'i' => $i);
 }
 
-$m = new Mongo();
-$c = $m->foo->bar->baz;
-$c->batchInsert($batch);
+$mongo = new Mongo();
+$collection = $mongo->my_db->users;
+$collection->drop();
 
-$cursor = $c->find()->sort(array("i" => 1));
-while ($cursor->hasNext()) {
-  $obj = $cursor->next();
-  var_dump($obj["i"]);
+$collection->batchInsert($users);
+
+foreach ($users as $user) {
+  echo $user['_id']."\n"; // populated with instanceof MongoId
 }
+
+$users = $collection->find()->sort(array('i' => 1));
+foreach ($users as $user) {
+    var_dump($user['username']);
+}
+
 ?>
 ]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
 <![CDATA[
-int(0)
-int(1)
-int(2)
+4bf43ac68ead0e1971000000
+4bf43ac68ead0e1971010000
+4bf43ac68ead0e1971020000
+...
+string(5) "user1"
+string(5) "user2"
+string(5) "user3"
 ...
 ]]>
    </screen>
diff --git a/reference/mongo/mongocollection/createdbref.xml b/reference/mongo/mongocollection/createdbref.xml
index 8f2c52cec6..ce8f5bc61a 100644
--- a/reference/mongo/mongocollection/createdbref.xml
+++ b/reference/mongo/mongocollection/createdbref.xml
@@ -43,7 +43,7 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title><function>MongoCollection::createDBRef</function> example</title>
+   <title><methodname>MongoCollection::createDBRef</methodname> example</title>
    <programlisting role="php">
 <![CDATA[
 <?php
diff --git a/reference/mongo/mongocollection/deleteindexes.xml b/reference/mongo/mongocollection/deleteindexes.xml
index babe3017f2..2af88ddf5e 100644
--- a/reference/mongo/mongocollection/deleteindexes.xml
+++ b/reference/mongo/mongocollection/deleteindexes.xml
@@ -27,6 +27,35 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>MongoCollection::deleteIndexes</function> example</title>
+   <para>This example demonstrates how to delete all indexes from a collection and the response to expect.</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$collection = $mongo->my_db->articles;
+$response = $collection->deleteIndexes();
+print_r($response);
+
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+Array
+(
+    [nIndexesWas] => 1
+    [msg] => all indexes deleted for collection
+    [ok] => 1
+)
+]]>
+   </screen>   
+  </example>  
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongocollection/drop.xml b/reference/mongo/mongocollection/drop.xml
index d824e1e014..c7a20890f0 100644
--- a/reference/mongo/mongocollection/drop.xml
+++ b/reference/mongo/mongocollection/drop.xml
@@ -29,6 +29,37 @@
    Returns the database response.
   </para>
  </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>MongoCollection::drop</function> example</title>
+   <para>This example demonstrates how to drop a collection and the response to expect.</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$collection = $mongo->my_db->articles;
+$response = $collection->drop();
+print_r($response);
+
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+Array
+(
+    [nIndexesWas] => 1
+    [msg] => all indexes deleted for collection
+    [ns] => my_db.articles
+    [ok] => 1
+)
+]]>
+   </screen>   
+  </example>  
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongocollection/find.xml b/reference/mongo/mongocollection/find.xml
index 471e2761fb..ae1d9260c1 100644
--- a/reference/mongo/mongocollection/find.xml
+++ b/reference/mongo/mongocollection/find.xml
@@ -65,6 +65,43 @@ $rangeQuery = array('x' => array( '$gt' => 5, '$lt' => 20 ));
 
 $cursor = $collection->find($rangeQuery);
 
+?>
+]]>
+   </programlisting>
+   <para>
+     See <classname>MongoCursor</classname> for more information how to work with cursors.
+   </para>
+  </example>
+  <example>
+   <title><function>MongoCollection::find</function> example using $where</title>
+   <para>This example demonstrates how to search a collection using javascript code to reduce the resultset.</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$collection = $db->my_db->articles;
+
+$js = "function() {
+  return this.type == 'homepage' || this.featured == true;
+}";
+$articles = $collection->find(array('$where' => $js));
+
+?>
+]]>
+   </programlisting>
+  </example>
+  <example>
+   <title><function>MongoCollection::find</function> example using $in</title>
+   <para>This example demonstrates how to search a collection using the $in operator.</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$collection = $db->my_db->articles;
+$articles = $collection->find(array(
+  'type' => array('$in' => array('homepage', 'editorial'))
+));
+
 ?>
 ]]>
    </programlisting>
diff --git a/reference/mongo/mongocollection/findone.xml b/reference/mongo/mongocollection/findone.xml
index d33a45554e..7e9a88d125 100644
--- a/reference/mongo/mongocollection/findone.xml
+++ b/reference/mongo/mongocollection/findone.xml
@@ -56,6 +56,57 @@
    database.
   </para>
  </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><methodname>MongoCollection::findOne</methodname> document by its id.</title>
+   <para>This example demonstrates how to find a single document in a collection by its id.</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$articles = $mongo->my_db->articles;
+
+$article = $articles->findOne(array('_id' => new MongoId('47cc67093475061e3d9536d2')));
+
+?>
+]]>
+   </programlisting>
+  </example>
+  <example>
+   <title><methodname>MongoCollection::findOne</methodname> document by some condition.</title>
+   <para>This example demonstrates how to find a single document in a collection by some condition and limiting the returned fields.</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$users = $mongo->my_db->users;
+$user = $users->findOne(array('username' => 'jwage'), array('password'));
+print_r($user);
+
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+Array
+(
+    [_id] => MongoId Object
+        (
+        )
+
+    [password] => test
+)
+]]>
+   </screen>
+   <para>
+    Notice how even though the document does have a username field, we limited the results
+    to only contain the password field.
+   </para>
+  </example>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongocollection/getdbref.xml b/reference/mongo/mongocollection/getdbref.xml
index 875aaf53e7..759d79f9ea 100644
--- a/reference/mongo/mongocollection/getdbref.xml
+++ b/reference/mongo/mongocollection/getdbref.xml
@@ -43,7 +43,7 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title><function>MongoCollection::createDBRef</function> example</title>
+   <title><methodname>MongoCollection::getDBRef</methodname> example</title>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -69,6 +69,16 @@ Ma na ma na
 Bohemian Rhapsody
 ]]>
    </screen>
+   <screen> 
+    In the above example each $songRef looks something like the following:
+    <![CDATA[
+    Array
+    (
+        [$ref] => songs
+        [$id] => 49902cde5162504500b45c2c
+    )
+    ]]>
+   </screen>
   </example>
  </refsect1>
 
diff --git a/reference/mongo/mongodb/createdbref.xml b/reference/mongo/mongodb/createdbref.xml
index 7c61ec6f14..3338c560da 100644
--- a/reference/mongo/mongodb/createdbref.xml
+++ b/reference/mongo/mongodb/createdbref.xml
@@ -56,6 +56,76 @@
    Returns a database reference array.
   </para>
  </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>MongoDB::createDBRef</function> example</title>
+   <para>
+    Example demonstrating how to programatically create a DB reference array from
+    a document.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$articles = $db->articles;
+
+$article = array(
+ 'title' => 'Test article',
+ 'description' => 'Test article description'
+);
+
+$articles->insert($article);
+$ref = $db->createDBRef('articles', $article);
+
+print_r($article);
+print_r($ref);
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+     <![CDATA[
+     Array
+     (
+         [title] => Test article
+         [description] => Test article description
+         [_id] => MongoId Object
+             (
+             )
+
+     )
+     Array
+     (
+         [$ref] => articles
+         [$id] => MongoId Object
+             (
+             )
+
+     )
+     ]]>
+   </screen>
+   <para>
+     Now the $ref can be stored on another document and retrieved later with
+     <methodname>MongoDB::getDBRef</methodname> or <methodname>MongoCollection::getDBRef</methodname>.
+   </para>
+  </example>
+  <example>
+   <title><function>MongoDB::createDBRef</function> example</title>
+   <para>
+    Example demonstrating how to programatically create a DB reference from just an id.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$id = new MongoId('47cc67093475061e3d9536d2');
+$ref = $db->createDBRef('articles', $id);
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongodb/drop.xml b/reference/mongo/mongodb/drop.xml
index 1da7786bc9..6707280260 100644
--- a/reference/mongo/mongodb/drop.xml
+++ b/reference/mongo/mongodb/drop.xml
@@ -26,6 +26,36 @@
    Returns the database response.
   </para>
  </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>MongoDB::drop</function> example</title>
+   <para>This example demonstrates how to drop a mongo database and the response to expect.</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$db = $mongo->foo;
+$response = $db->drop();
+print_r($response);
+
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+Array
+(
+    [dropped] => foo.$cmd
+    [ok] => 1
+)
+]]>
+   </screen>
+  </example>  
+ </refsect1>
+
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongodb/getdbref.xml b/reference/mongo/mongodb/getdbref.xml
index c0b03861f3..9539423875 100644
--- a/reference/mongo/mongodb/getdbref.xml
+++ b/reference/mongo/mongodb/getdbref.xml
@@ -39,6 +39,32 @@
    Returns the document pointed to by the reference.
   </para>
  </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>MongoDB::getDBRef</function> example</title>
+   <para>
+    Example demonstrating how to get a database reference and what the expected
+    input is.
+   </para>
+   <programlisting role="php">
+ <![CDATA[
+ <?php
+
+ $ref = array(
+   '$ref' => 'profiles',
+   '$id' => '47cc67093475061e3d9536d2'
+ );
+ 
+ $profile = $db->getDBRef($ref);
+ ?>
+ ]]>
+    <para>
+     See <function>MongoDB::createDBRef</function> for more information about how to programatically create DB references.
+    </para>
+   </programlisting>
+  </example>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongodb/getgridfs.xml b/reference/mongo/mongodb/getgridfs.xml
index 4878550893..1060a7eb98 100644
--- a/reference/mongo/mongodb/getgridfs.xml
+++ b/reference/mongo/mongodb/getgridfs.xml
@@ -39,6 +39,30 @@
    Returns a new gridfs object for this database.
   </para>
  </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>MongoDB::getGridFS</function> example</title>
+   <para>This example demonstrates how get a MongoGridFS instance.</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$db = $mongo->my_db;
+
+$prefix = 'files';
+$collection = $db->getGridFS($prefix);
+
+?>
+]]>
+   </programlisting>
+   <para>
+    Read more about the <classname>MongoGridFS</classname> to learn how to store files with MongoDB.
+   </para>
+  </example>  
+ </refsect1>
+
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongodb/repair.xml b/reference/mongo/mongodb/repair.xml
index d46a74583a..1e8d1bdf6f 100644
--- a/reference/mongo/mongodb/repair.xml
+++ b/reference/mongo/mongodb/repair.xml
@@ -58,6 +58,35 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>MongoDB::repair</function> example</title>
+   <para>This example demonstrates how to repare and compact a database.</para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$db = $mongo->foo;
+
+$response = $db->repair();
+print_r($response);
+
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+Array
+(
+    [ok] => 1
+)
+]]>
+   </screen>
+  </example>  
+ </refsect1>
+
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongogridfs/findone.xml b/reference/mongo/mongogridfs/findone.xml
index 17ae5c82a3..c724f15713 100644
--- a/reference/mongo/mongogridfs/findone.xml
+++ b/reference/mongo/mongogridfs/findone.xml
@@ -39,6 +39,68 @@
    Returns a <classname>MongoGridFSFile</classname> or &null;.
   </para>
  </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><methodname>MongoGridFS::findOne</methodname> example</title>
+   <para>
+    Example demonstrating how to find a single file from the MongoGridFS.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$downloads = $mongo->my_db->getGridFS('downloads');
+
+$downloads->storeFile('filename.tgz');
+
+$download = $downloads->findOne('filename.tgz'); // instance of MongoGridFSFile
+
+print_r($download);
+?>
+]]>
+    <para>
+     See <classname>MongoGridFSFile</classname> for more information about how to work with files.
+    </para>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+MongoGridFSFile Object
+(
+    [file] => Array
+        (
+            [_id] => MongoId Object
+                (
+                )
+
+            [filename] => filename.tgz
+            [uploadDate] => MongoDate Object
+                (
+                    [sec] => 1274288014
+                    [usec] => 467000
+                )
+
+            [chunkSize] => 262144
+            [md5] => d41d8cd98f00b204e9800998ecf8427e
+        )
+
+    [gridfs:protected] => MongoGridFS Object
+        (
+            [chunks] => MongoCollection Object
+                (
+                )
+
+            [filesName:protected] => downloads.files
+            [chunksName:protected] => downloads.chunks
+        )
+
+)
+]]>
+   </screen>
+  </example>
+ </refsect1>
 
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/mongo/mongogridfsfile/getbytes.xml b/reference/mongo/mongogridfsfile/getbytes.xml
index 901c9ed10d..c7d60e7c1c 100644
--- a/reference/mongo/mongogridfsfile/getbytes.xml
+++ b/reference/mongo/mongogridfsfile/getbytes.xml
@@ -30,6 +30,27 @@
    Returns a string of the bytes in the file.
   </para>
  </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><methodname>MongoGridFSFile::getBytes</methodname> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$images = $db->my_db->getGridFS('images');
+
+$image = $images->findOne('jwage.png');
+
+header('Content-type: image/png;');
+echo $image->getBytes();
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongogridfsfile/write.xml b/reference/mongo/mongogridfsfile/write.xml
index a2a6dbcf62..59a78fff90 100644
--- a/reference/mongo/mongogridfsfile/write.xml
+++ b/reference/mongo/mongogridfsfile/write.xml
@@ -37,6 +37,24 @@
    Returns the number of bytes written.
   </para>
  </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><methodname>MongoGridFSFile::write</methodname> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$images = $db->my_db->getGridFS('images');
+
+$image = $images->findOne('jwage.png');
+$image->write('/path/to/write/jwage.png');
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables: