<!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> [, <span class="methodparam"><span class="type">array</span> <code class="parameter">$options</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> <code class="parameter">query</code> </dt> <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="https://docs.mongodb.com/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> <code class="parameter">fields</code> </dt> <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> <code class="parameter">options</code> </dt> <dd> <p class="para"> This parameter is an associative array of the form <em>array("name" => <value>, ...)</em>. Currently supported options are: </p> <ul class="itemizedlist"> <li class="listitem"><p class="para"><em>"maxTimeMS"</em></p><p class="para">Specifies a cumulative time limit in milliseconds for processing the operation on the server (does not include idle time). If the operation is not completed by the server within the timeout period, a <a href="class.mongoexecutiontimeoutexception.html" class="classname">MongoExecutionTimeoutException</a> will be thrown.</p></li> </ul> </dd> </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 changelog" id="refsect1-mongocollection.findone-changelog"> <h3 class="title">Changelog</h3> <table class="doctable informaltable"> <thead> <tr> <th>Version</th> <th>Description</th> </tr> </thead> <tbody class="tbody"> <tr> <td>1.5.0</td> <td> Added optional <code class="parameter">options</code> argument. </td> </tr> </tbody> </table> </div> <div class="refsect1 examples" id="refsect1-mongocollection.findone-examples"> <h3 class="title">Examples</h3> <div class="example" id="example-1591"> <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-1592"> <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="https://docs.mongodb.com/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>