From a174aaabf47530d7907b5b05691f01d98bb34877 Mon Sep 17 00:00:00 2001
From: Derick Rethans <derick@php.net>
Date: Mon, 22 Apr 2013 14:47:30 +0000
Subject: [PATCH] PHP-496: Added a few examples to MongoDB::command() and
 clarified result structures.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@330129 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongo/mongodb/command.xml | 129 +++++++++++++++++++++++++++-
 1 file changed, 125 insertions(+), 4 deletions(-)

diff --git a/reference/mongo/mongodb/command.xml b/reference/mongo/mongodb/command.xml
index fecea87caf..6f996278af 100644
--- a/reference/mongo/mongodb/command.xml
+++ b/reference/mongo/mongodb/command.xml
@@ -14,9 +14,10 @@
    <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Almost everything that is not a CRUD operation can be done with a database command.
-   Need to know the database version?  There's a command for that.  Need to do aggregation?
-   There's a command for that.  Need to turn up logging?  You get the idea.
+   Almost everything that is not a CRUD operation can be done with a database
+   command.  Need to know the database version?  There's a command for that.
+   Need to do aggregation?  There's a command for that.  Need to turn up
+   logging?  You get the idea.
   </para>
   <para>
    This method is identical to:
@@ -94,9 +95,15 @@ public function command($data) {
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;  
   <para>
-   Returns database response.
+   Returns database response. Every database response is always maximum one
+   document, which means that the result of a database command can never
+   exceed 16MB. The resulting document's structure depends on the command, but
+   most results will have the <literal>ok</literal> field to indicate success
+   or failure and <literal>results</literal> containing an array of each of
+   the resulting documents.
   </para>
  </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
@@ -131,6 +138,7 @@ foreach ($ages['values'] as $age) {
 87
    </screen>
   </example>
+
   <example>
    <title><function>MongoDB::command</function> "distinct" example</title>
    <para>
@@ -169,6 +177,7 @@ foreach ($ages['values'] as $age) {
 87
    </screen>
   </example>
+
   <example>
    <title><function>MongoDB::command</function> MapReduce example</title>
    <para>
@@ -249,10 +258,122 @@ User 4af467e4fd543cce7b0ea8e2 had 1 sale(s).
     on how to use it.
    </para>
   </example>
+
+  <example>
+   <title><function>MongoDB::command</function> "textSearch" example</title>
+   <para>
+    Do a fulltext search lookup with MongoDB's 2.4 and higher "text search"
+    functionality.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$m = new MongoClient();
+$d = $m->demo;
+$c = $d->planets;
+
+$c->insert(array("name" => "Mercury", "desc" => "Mercury is the smallest and closest to the Sun"));
+$c->insert(array("name" => "Venus", "desc" => "Venus is the second planet from the Sun, orbiting it every 224.7 Earth days."));
+$c->insert(array("name" => "Earth", "desc" => "Earth is the the densest of the eight planets in the Solar System."));
+$c->insert(array("name" => "Mars", "desc" => "Mars is named after the Roman god of war."));
+
+$c->ensureIndex(array('desc' => 'text'));
+
+$r = $d->command(array("text" => "planets", 'search' => "sun" ));
+print_r($r);
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+Array
+(
+    [queryDebugString] => sun||||||
+    [language] => english
+    [results] => Array
+        (
+            [0] => Array
+                (
+                    [score] => 0.625
+                    [obj] => Array
+                        (
+                            [_id] => MongoId Object
+                                (
+                                    [$id] => 517549d944670a4a5cb3059a
+                                )
+
+                            [name] => Mercury
+                            [desc] => Mercury is the smallest and closest to the Sun
+                        )
+
+                )
+
+            [1] => Array
+                (
+                    [score] => 0.55
+                    [obj] => Array
+                        (
+                            [_id] => MongoId Object
+                                (
+                                    [$id] => 517549d944670a4a5cb3059b
+                                )
+
+                            [name] => Venus
+                            [desc] => Venus is the second planet from the Sun, orbiting it every 224.7 Earth days.
+                        )
+
+                )
+
+        )
+
+    [stats] => Array
+        (
+            [nscanned] => 2
+            [nscannedObjects] => 0
+            [n] => 2
+            [nfound] => 2
+            [timeMicros] => 95
+        )
+
+    [ok] => 1
+)
+   </screen>
+  </example>
+
+  <example>
+   <title><function>MongoDB::command</function> "geoNear" example</title>
+   <para>
+    This example shows how to use the geoNear command.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$m = new MongoClient();
+$d = $m->demo;
+$c = $d->poiConcat;
+
+$r = $d->command(array(
+    'geoNear' => "poiConcat",      // Search in the poiConcat collection
+    'near' => array(-0.08, 51.48), // Search near 51.48°N, 0.08°E
+    'spherical' => true,           // Enable spherical search
+    'num' => 5,                    // Maximum 5 returned documents
+));
+print_r($r);
+?>
+]]>
+   </programlisting>
+  </example>
  </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>MongoCollection::aggregate</methodname></member>
+    <member><methodname>MongoCollection::findAndModify</methodname></member>
+    <member><methodname>MongoCollection::group</methodname></member>
+   </simplelist>
+  </para>
   <para>
    MongoDB core docs on 
    <link xlink:href="&url.mongodb.dochub.commands;">database commands</link>