<!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>Finding Documents using MongoCollection::findOne</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongo.tutorial.insert.html">Inserting a Document</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongo.tutorial.insert.multiple.html">Adding Multiple Documents</a></div>
<div class="up"><a href="mongo.tutorial.html">Tutorial</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongo.tutorial.findone" class="section">
<h2 class="title">
Finding Documents using <span class="function"><a href="mongocollection.findone.html" class="function">MongoCollection::findOne()</a></span>
</h2>
<p class="para">
To show that the document we inserted in the previous step is stored in
the database, we can do a simple
<span class="function"><a href="mongocollection.findone.html" class="function">MongoCollection::findOne()</a></span> operation to get a single
document from the collection. This method is useful when there is only one
document matching the query or you are only interested in one result.
</p>
<div class="example" id="mongo.tutorial.findone-example">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$connection </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$collection </span><span style="color: #007700">= </span><span style="color: #0000BB">$connection</span><span style="color: #007700">-></span><span style="color: #0000BB">database</span><span style="color: #007700">-></span><span style="color: #0000BB">collectionName</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$document </span><span style="color: #007700">= </span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">findOne</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">( </span><span style="color: #0000BB">$document </span><span style="color: #007700">);<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(6) {
["_id"]=>
object(MongoId)#8 (1) {
["$id"]=>
string(24) "4e2995576803fab768000000"
}
["name"]=>
string(7) "MongoDB"
["type"]=>
string(8) "database"
["count"]=>
int(1)
["info"]=>
array(2) {
["x"]=>
int(203)
["y"]=>
int(102)
}
["versions"]=>
array(3) {
[0]=>
string(5) "0.9.7"
[1]=>
string(5) "0.9.8"
[2]=>
string(5) "0.9.9"
}
}
</pre></div>
</div>
</div>
<p class="para">
Note that there is an <em>_id</em> field that has been added
automatically to your document. <em>_id</em> is the "primary key"
field. If your document does not specify one, the driver will add one
automatically.
</p>
<p class="para">
If you specify your own <em>_id</em> field, it must be unique to
the collection. See the example here:
</p>
<div class="example" id="mongo.tutorial.findone-example-2">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$connection </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">$connection</span><span style="color: #007700">-></span><span style="color: #0000BB">database</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$db</span><span style="color: #007700">-></span><span style="color: #0000BB">foo</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"_id" </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /></span><span style="color: #FF8000">// this will throw an exception<br /></span><span style="color: #0000BB">$db</span><span style="color: #007700">-></span><span style="color: #0000BB">foo</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"_id" </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">// this is fine, as it is a different collection<br /></span><span style="color: #0000BB">$db</span><span style="color: #007700">-></span><span style="color: #0000BB">bar</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"_id" </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<p class="para">
By default the driver will ensure the server has acknowledged the write
before returning. You can optionally turn this behaviour off by passing
<em>array("w" => 0)</em> as the second argument. This means that
the driver should not wait for the database to acknowledge the write and
would not throw the duplicate <em>_id</em> exception.
</p>
<div class="section" id="mongo.tutorial.findone.seealso">
<h2 class="title">See Also</h2>
<p class="para">
<span class="function"><a href="mongocollection.findone.html" class="function">MongoCollection::findOne()</a></span> for more information about
finding data.
</p>
<p class="para">
<a href="class.mongoid.html" class="classname">MongoId</a> goes into more detail on unique ids.
</p>
<p class="para">
The <a href="mongo.writes.html" class="link">writes</a> section covers
writes in more depth, and the <a href="mongo.writeconcerns.html" class="xref">Write Concerns</a>
chapter goes into details of the various Write Concern options.
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongo.tutorial.insert.html">Inserting a Document</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongo.tutorial.insert.multiple.html">Adding Multiple Documents</a></div>
<div class="up"><a href="mongo.tutorial.html">Tutorial</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
