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
This commit is contained in:
Derick Rethans 2013-04-22 14:47:30 +00:00
parent 53281c346b
commit a174aaabf4

View file

@ -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>