<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Queries this collection, returning a MongoCursor
for the result set</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongocollection.ensureindex.html">MongoCollection::ensureIndex</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongocollection.findandmodify.html">MongoCollection::findAndModify</a></div>
<div class="up"><a href="class.mongocollection.html">MongoCollection</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongocollection.find" class="refentry">
<div class="refnamediv">
<h1 class="refname">MongoCollection::find</h1>
<p class="verinfo">(PECL mongo >=0.9.0)</p><p class="refpurpose"><span class="refname">MongoCollection::find</span> — <span class="dc-title">Queries this collection, returning a <a href="class.mongocursor.html" class="classname">MongoCursor</a>
for the result set</span></p>
</div>
<div class="refsect1 description" id="refsect1-mongocollection.find-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type"><a href="class.mongocursor.html" class="type MongoCursor">MongoCursor</a></span> <span class="methodname"><strong>MongoCollection::find</strong></span>
([ <span class="methodparam"><span class="type">array</span> <code class="parameter">$query</code><span class="initializer"> = array()</span></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$fields</code><span class="initializer"> = array()</span></span>
]] )</div>
</div>
<div class="refsect1 parameters" id="refsect1-mongocollection.find-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term">
<em><code class="parameter">query</code></em>
</span>
<dd>
<p class="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
<a href="http://docs.mongodb.org/manual/reference/method/db.collection.find/" class="link external">» find</a> is a good idea.
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
Please make sure that for all special query operators (starting with
<em>$</em>) you use single quotes so that PHP doesn't try to
replace <em>"$exists"</em> with the value of the variable
<em>$exists</em>.
</p>
</div>
</dd>
</dt>
<dt>
<span class="term">
<em><code class="parameter">fields</code></em>
</span>
<dd>
<p class="para">
Fields of the results to return. The array is in the format
<em>array('fieldname' => true, 'fieldname2' => true)</em>.
The <em>_id</em> field is always returned.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-mongocollection.find-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns a cursor for the search results.
</p>
</div>
<div class="refsect1 examples" id="refsect1-mongocollection.find-examples">
<h3 class="title">Examples</h3>
<div class="example" id="example-1446">
<p><strong>Example #1 <span class="function"><strong>MongoCollection::find()</strong></span> example</strong></p>
<div class="example-contents"><p>This example demonstrates basic search options.</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$db </span><span style="color: #007700">= </span><span style="color: #0000BB">$m</span><span style="color: #007700">-></span><span style="color: #0000BB">selectDB</span><span style="color: #007700">(</span><span style="color: #DD0000">'test'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$collection </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoCollection</span><span style="color: #007700">(</span><span style="color: #0000BB">$db</span><span style="color: #007700">, </span><span style="color: #DD0000">'produce'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// search for fruits<br /></span><span style="color: #0000BB">$fruitQuery </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'Type' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'Fruit'</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$cursor </span><span style="color: #007700">= </span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">find</span><span style="color: #007700">(</span><span style="color: #0000BB">$fruitQuery</span><span style="color: #007700">);<br />foreach (</span><span style="color: #0000BB">$cursor </span><span style="color: #007700">as </span><span style="color: #0000BB">$doc</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$doc</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #FF8000">// search for produce that is sweet. Taste is a child of Details. <br /></span><span style="color: #0000BB">$sweetQuery </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'Details.Taste' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'Sweet'</span><span style="color: #007700">);<br />echo </span><span style="color: #DD0000">"Sweet\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$cursor </span><span style="color: #007700">= </span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">find</span><span style="color: #007700">(</span><span style="color: #0000BB">$sweetQuery</span><span style="color: #007700">);<br />foreach (</span><span style="color: #0000BB">$cursor </span><span style="color: #007700">as </span><span style="color: #0000BB">$doc</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$doc</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
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"
}
}
</pre></div>
</div>
<div class="example-contents"><p>
See <a href="class.mongocursor.html" class="classname">MongoCursor</a> for more information how to work with cursors.
</p></div>
</div>
<div class="example" id="example-1447">
<p><strong>Example #2 <span class="function"><strong>MongoCollection::find()</strong></span> example</strong></p>
<div class="example-contents"><p>This example demonstrates how to search for a range.</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$db </span><span style="color: #007700">= </span><span style="color: #0000BB">$m</span><span style="color: #007700">-></span><span style="color: #0000BB">selectDB</span><span style="color: #007700">(</span><span style="color: #DD0000">'test'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$collection </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoCollection</span><span style="color: #007700">(</span><span style="color: #0000BB">$db</span><span style="color: #007700">, </span><span style="color: #DD0000">'phpmanual'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// search for documents where 5 < x < 20<br /></span><span style="color: #0000BB">$rangeQuery </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'x' </span><span style="color: #007700">=> array( </span><span style="color: #DD0000">'$gt' </span><span style="color: #007700">=> </span><span style="color: #0000BB">5</span><span style="color: #007700">, </span><span style="color: #DD0000">'$lt' </span><span style="color: #007700">=> </span><span style="color: #0000BB">20 </span><span style="color: #007700">));<br /><br /></span><span style="color: #0000BB">$cursor </span><span style="color: #007700">= </span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">find</span><span style="color: #007700">(</span><span style="color: #0000BB">$rangeQuery</span><span style="color: #007700">);<br />foreach (</span><span style="color: #0000BB">$cursor </span><span style="color: #007700">as </span><span style="color: #0000BB">$doc</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$doc</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
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)
}
</pre></div>
</div>
<div class="example-contents"><p>
See <a href="class.mongocursor.html" class="classname">MongoCursor</a> for more information how to work with cursors.
</p></div>
</div>
<div class="example" id="example-1448">
<p><strong>Example #3 <span class="function"><strong>MongoCollection::find()</strong></span> example using $where</strong></p>
<div class="example-contents"><p>This example demonstrates how to search a collection using javascript code to reduce the resultset.</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$db </span><span style="color: #007700">= </span><span style="color: #0000BB">$m</span><span style="color: #007700">-></span><span style="color: #0000BB">selectDB</span><span style="color: #007700">(</span><span style="color: #DD0000">'test'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$collection </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoCollection</span><span style="color: #007700">(</span><span style="color: #0000BB">$db</span><span style="color: #007700">, </span><span style="color: #DD0000">'phpmanual'</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$js </span><span style="color: #007700">= </span><span style="color: #DD0000">"function() {<br /> return this.name == 'Joe' || this.age == 50;<br />}"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$cursor </span><span style="color: #007700">= </span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">find</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'$where' </span><span style="color: #007700">=> </span><span style="color: #0000BB">$js</span><span style="color: #007700">));<br />foreach (</span><span style="color: #0000BB">$cursor </span><span style="color: #007700">as </span><span style="color: #0000BB">$doc</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$doc</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
array(3) {
["_id"]=>
object(MongoId)#7 (1) {
["$id"]=>
string(24) "4ebc3e3710b89f2349000002"
}
["name"]=>
string(3) "Joe"
["age"]=>
int(20)
}
</pre></div>
</div>
</div>
<div class="example" id="example-1449">
<p><strong>Example #4 <span class="function"><strong>MongoCollection::find()</strong></span> example using $in</strong></p>
<div class="example-contents"><p>This example demonstrates how to search a collection using the $in operator.</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$db </span><span style="color: #007700">= </span><span style="color: #0000BB">$m</span><span style="color: #007700">-></span><span style="color: #0000BB">selectDB</span><span style="color: #007700">(</span><span style="color: #DD0000">'test'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$collection </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoCollection</span><span style="color: #007700">(</span><span style="color: #0000BB">$db</span><span style="color: #007700">, </span><span style="color: #DD0000">'phpmanual'</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$cursor </span><span style="color: #007700">= </span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">find</span><span style="color: #007700">(array(<br /> </span><span style="color: #DD0000">'name' </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">'$in' </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">'Joe'</span><span style="color: #007700">, </span><span style="color: #DD0000">'Wendy'</span><span style="color: #007700">))<br />));<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
array(3) {
["_id"]=>
object(MongoId)#7 (1) {
["$id"]=>
string(24) "4ebc3e3710b89f2349000002"
}
["name"]=>
string(3) "Joe"
["age"]=>
int(20)
}
</pre></div>
</div>
</div>
<div class="example" id="example-1450">
<p><strong>Example #5 Getting results as an array</strong></p>
<div class="example-contents"><p>
This returns a <a href="class.mongocursor.html" class="classname">MongoCursor</a>. Often, when people are
starting out, they are more comfortable using an array. To turn a cursor
into an array, use the <span class="function"><a href="function.iterator-to-array.html" class="function">iterator_to_array()</a></span> function.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$db </span><span style="color: #007700">= </span><span style="color: #0000BB">$m</span><span style="color: #007700">-></span><span style="color: #0000BB">selectDB</span><span style="color: #007700">(</span><span style="color: #DD0000">'test'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$collection </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoCollection</span><span style="color: #007700">(</span><span style="color: #0000BB">$db</span><span style="color: #007700">, </span><span style="color: #DD0000">'phpmanual'</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$cursor </span><span style="color: #007700">= </span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">find</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$array </span><span style="color: #007700">= </span><span style="color: #0000BB">iterator_to_array</span><span style="color: #007700">(</span><span style="color: #0000BB">$cursor</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
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)
}
}
</pre></div>
</div>
<div class="example-contents"><p>
Using <span class="function"><a href="function.iterator-to-array.html" class="function">iterator_to_array()</a></span> forces the driver to load all of
the results into memory, so do not do this for result sets that are larger
than memory!
</p></div>
<div class="example-contents"><p>
Also, certain system collections do not have an <em>_id</em>
field. If you are dealing with a collection that might have documents
without <em>_id</em>s, pass <strong><code>FALSE</code></strong> as the second argument to
<span class="function"><a href="function.iterator-to-array.html" class="function">iterator_to_array()</a></span> (so that it will not try to use the
non-existent <em>_id</em> values as keys).
</p></div>
</div>
</div>
<div class="refsect1 seealso" id="refsect1-mongocollection.find-seealso">
<h3 class="title">See Also</h3>
<ul class="simplelist">
<li class="member"> <span class="function"><a href="mongocollection.findone.html" class="function" rel="rdfs-seeAlso">MongoCollection::findOne()</a> - Queries this collection, returning a single element</span></li>
<li class="member"> <span class="function"><a href="mongocollection.insert.html" class="function" rel="rdfs-seeAlso">MongoCollection::insert()</a> - Inserts a document into the collection</span></li>
<li class="member">MongoDB core docs on <a href="http://docs.mongodb.org/manual/reference/method/db.collection.find/" class="link external">» find</a>.</li>
</ul>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongocollection.ensureindex.html">MongoCollection::ensureIndex</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongocollection.findandmodify.html">MongoCollection::findAndModify</a></div>
<div class="up"><a href="class.mongocollection.html">MongoCollection</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
