<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision: 332331 $ -->
<refentry xml:id="mongocollection.find" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoCollection::find</refname>
  <refpurpose>Queries this collection, returning a <classname>MongoCursor</classname>
  for the result set</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>MongoCursor</type><methodname>MongoCollection::find</methodname>
   <methodparam choice="opt"><type>array</type><parameter>query</parameter><initializer>array()</initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>fields</parameter><initializer>array()</initializer></methodparam>
  </methodsynopsis>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;  
  <para>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>query</parameter>
     </term>
     <listitem>
      <para>
       The fields for which to search. MongoDB's query language is quite
       extensive. The PHP driver will in almost all cases pass the query
       straight through to the server, so reading the MongoDB core docs on
       <link xlink:href="&url.mongodb.dochub.find;">find</link> is a good idea.
      </para>
      <warning>
       <para>
        Please make sure that for all special query operators (starting with
        <literal>$</literal>) you use single quotes so that PHP doesn't try to
        replace <literal>"$exists"</literal> with the value of the variable
        <literal>$exists</literal>.
       </para>
      </warning>
     </listitem>
    </varlistentry>   
    <varlistentry>
     <term>
      <parameter>fields</parameter>
     </term>
     <listitem>
      <para>
       Fields of the results to return. The array is in the format
       <literal>array('fieldname' => true, 'fieldname2' => true)</literal>.
       The <literal>_id</literal> field is always returned.
      </para>
     </listitem>
    </varlistentry>   
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a cursor for the search results.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
   <example>
   <title><function>MongoCollection::find</function> example</title>
   <para>This example demonstrates basic search options.</para>
   <programlisting role="php">
<![CDATA[
<?php

$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'produce');

// search for fruits
$fruitQuery = array('Type' => 'Fruit');

$cursor = $collection->find($fruitQuery);
foreach ($cursor as $doc) {
    var_dump($doc);
}

// search for produce that is sweet. Taste is a child of Details. 
$sweetQuery = array('Details.Taste' => 'Sweet');
echo "Sweet\n";
$cursor = $collection->find($sweetQuery);
foreach ($cursor as $doc) {
    var_dump($doc);
}

?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
array(4) {
  ["_id"]=>
  object(MongoId)#7 (1) {
    ["$id"]=>
    string(24) "50a87dd084f045a19b220dd6"
  }
  ["Name"]=>
  string(5) "Apple"
  ["Type"]=>
  string(5) "Fruit"
  ["Details"]=>
  array(2) {
    ["Taste"]=>
    string(5) "Sweet"
    ["Colour"]=>
    string(3) "Red"
  }
}
array(4) {
  ["_id"]=>
  object(MongoId)#8 (1) {
    ["$id"]=>
    string(24) "50a87de084f045a19b220dd7"
  }
  ["Name"]=>
  string(5) "Lemon"
  ["Type"]=>
  string(5) "Fruit"
  ["Details"]=>
  array(2) {
    ["Taste"]=>
    string(4) "Sour"
    ["Colour"]=>
    string(5) "Green"
  }
}

Sweet:
array(4) {
  ["_id"]=>
  object(MongoId)#7 (1) {
    ["$id"]=>
    string(24) "50a87dd084f045a19b220dd6"
  }
  ["Name"]=>
  string(5) "Apple"
  ["Type"]=>
  string(5) "Fruit"
  ["Details"]=>
  array(2) {
    ["Taste"]=>
    string(5) "Sweet"
    ["Colour"]=>
    string(3) "Red"
  }
}
]]>
   </screen>
   <para>
     See <classname>MongoCursor</classname> for more information how to work with cursors.
   </para>
  </example>
  <example>
   <title><function>MongoCollection::find</function> example</title>
   <para>This example demonstrates how to search for a range.</para>
   <programlisting role="php">
<![CDATA[
<?php

$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');

// search for documents where 5 < x < 20
$rangeQuery = array('x' => array( '$gt' => 5, '$lt' => 20 ));

$cursor = $collection->find($rangeQuery);
foreach ($cursor as $doc) {
    var_dump($doc);
}

?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
array(2) {
  ["_id"]=>
  object(MongoId)#10 (1) {
    ["$id"]=>
    string(24) "4ebc3e3710b89f2349000000"
  }
  ["x"]=>
  int(12)
}
array(2) {
  ["_id"]=>
  object(MongoId)#11 (1) {
    ["$id"]=>
    string(24) "4ebc3e3710b89f2349000001"
  }
  ["x"]=>
  int(12)
}
]]>
   </screen>
   <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

$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');

$js = "function() {
    return this.name == 'Joe' || this.age == 50;
}";
$cursor = $collection->find(array('$where' => $js));
foreach ($cursor as $doc) {
    var_dump($doc);
}

?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
array(3) {
  ["_id"]=>
  object(MongoId)#7 (1) {
    ["$id"]=>
    string(24) "4ebc3e3710b89f2349000002"
  }
  ["name"]=>
  string(3) "Joe"
  ["age"]=>
  int(20)
}
]]>
   </screen>
  </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

$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');

$cursor = $collection->find(array(
    'name' => array('$in' => array('Joe', 'Wendy'))
));

?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
array(3) {
  ["_id"]=>
  object(MongoId)#7 (1) {
    ["$id"]=>
    string(24) "4ebc3e3710b89f2349000002"
  }
  ["name"]=>
  string(3) "Joe"
  ["age"]=>
  int(20)
}
]]>
   </screen>
  </example>

  <example>
   <title>Getting results as an array</title>
   <para>
    This returns a <classname>MongoCursor</classname>.  Often, when people are 
    starting out, they are more comfortable using an array.  To turn a cursor
    into an array, use the <function>iterator_to_array</function> function.  
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');

$cursor = $collection->find();
$array = iterator_to_array($cursor);

?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
array(3) {
  ["4ebc40af10b89f5149000000"]=>
  array(2) {
    ["_id"]=>
    object(MongoId)#6 (1) {
      ["$id"]=>
      string(24) "4ebc40af10b89f5149000000"
    }
    ["x"]=>
    int(12)
  }
  ["4ebc40af10b89f5149000001"]=>
  array(2) {
    ["_id"]=>
    object(MongoId)#11 (1) {
      ["$id"]=>
      string(24) "4ebc40af10b89f5149000001"
    }
    ["x"]=>
    int(12)
  }
  ["4ebc40af10b89f5149000002"]=>
  array(3) {
    ["_id"]=>
    object(MongoId)#12 (1) {
      ["$id"]=>
      string(24) "4ebc40af10b89f5149000002"
    }
    ["name"]=>
    string(3) "Joe"
    ["age"]=>
    int(20)
  }
}
]]>
   </screen>
   <para>
    Using <function>iterator_to_array</function> forces the driver to load all of
    the results into memory, so do not do this for result sets that are larger
    than memory!
   </para>
   <para>
    Also, certain system collections do not have an <literal>_id</literal> 
    field.  If you are dealing with a collection that might have documents 
    without <literal>_id</literal>s, pass &false; as the second argument to
    <function>iterator_to_array</function> (so that it will not try to use the
    non-existent <literal>_id</literal> values as keys).
   </para>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>MongoCollection::findOne</function></member>
   <member><function>MongoCollection::insert</function></member>
   <member>MongoDB core docs on <link xlink:href="&url.mongodb.dochub.find;">find</link>.</member>
  </simplelist>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->