<!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 single element</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongocollection.findandmodify.html">MongoCollection::findAndModify</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongocollection.get.html">MongoCollection::__get</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.findone" class="refentry">
<div class="refnamediv">
<h1 class="refname">MongoCollection::findOne</h1>
<p class="verinfo">(PECL mongo >=0.9.0)</p><p class="refpurpose"><span class="refname">MongoCollection::findOne</span> — <span class="dc-title">Queries this collection, returning a single element</span></p>
</div>
<div class="refsect1 description" id="refsect1-mongocollection.findone-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">array</span> <span class="methodname"><strong>MongoCollection::findOne</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>
<p class="para rdfs-comment">
As opposed to <span class="function"><a href="mongocollection.find.html" class="function">MongoCollection::find()</a></span>, this method
will return only the <em class="emphasis">first</em> result from the result set,
and not a <a href="class.mongocursor.html" class="classname">MongoCursor</a> that can be iterated over.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-mongocollection.findone-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 operaters (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.findone-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns record matching the search or <strong><code>NULL</code></strong>.
</p>
</div>
<div class="refsect1 errors" id="refsect1-mongocollection.findone-errors">
<h3 class="title">Errors/Exceptions</h3>
<p class="para">
Throws <a href="class.mongoconnectionexception.html" class="classname">MongoConnectionException</a> if it cannot reach the
database.
</p>
</div>
<div class="refsect1 examples" id="refsect1-mongocollection.findone-examples">
<h3 class="title">Examples</h3>
<div class="example" id="example-1453">
<p><strong>Example #1 <span class="methodname"><strong>MongoCollection::findOne()</strong></span> document by its id.</strong></p>
<div class="example-contents"><p>This example demonstrates how to find a single document in a collection by its id.</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$articles </span><span style="color: #007700">= </span><span style="color: #0000BB">$mongo</span><span style="color: #007700">-></span><span style="color: #0000BB">my_db</span><span style="color: #007700">-></span><span style="color: #0000BB">articles</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$article </span><span style="color: #007700">= </span><span style="color: #0000BB">$articles</span><span style="color: #007700">-></span><span style="color: #0000BB">findOne</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'_id' </span><span style="color: #007700">=> new </span><span style="color: #0000BB">MongoId</span><span style="color: #007700">(</span><span style="color: #DD0000">'47cc67093475061e3d9536d2'</span><span style="color: #007700">)));<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="example-1454">
<p><strong>Example #2 <span class="methodname"><strong>MongoCollection::findOne()</strong></span> document by some condition.</strong></p>
<div class="example-contents"><p>This example demonstrates how to find a single document in a collection by some condition and limiting the returned fields.</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$users </span><span style="color: #007700">= </span><span style="color: #0000BB">$mongo</span><span style="color: #007700">-></span><span style="color: #0000BB">my_db</span><span style="color: #007700">-></span><span style="color: #0000BB">users</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$user </span><span style="color: #007700">= </span><span style="color: #0000BB">$users</span><span style="color: #007700">-></span><span style="color: #0000BB">findOne</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'username' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'jwage'</span><span style="color: #007700">), array(</span><span style="color: #DD0000">'password'</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$user</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
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Array
(
[_id] => MongoId Object
(
)
[password] => test
)
</pre></div>
</div>
<div class="example-contents"><p>
Notice how even though the document does have a username field, we limited the results
to only contain the password field.
</p></div>
</div>
</div>
<div class="refsect1 seealso" id="refsect1-mongocollection.findone-seealso">
<h3 class="title">See Also</h3>
<ul class="simplelist">
<li class="member"> <span class="function"><a href="mongocollection.find.html" class="function" rel="rdfs-seeAlso">MongoCollection::find()</a> - Queries this collection, returning a MongoCursor
for the result set</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.findandmodify.html">MongoCollection::findAndModify</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongocollection.get.html">MongoCollection::__get</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>
