<!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>Update a document and return it</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongocollection.find.html">MongoCollection::find</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongocollection.findone.html">MongoCollection::findOne</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.findandmodify" class="refentry">
<div class="refnamediv">
<h1 class="refname">MongoCollection::findAndModify</h1>
<p class="verinfo">(PECL mongo >=1.3.0)</p><p class="refpurpose"><span class="refname">MongoCollection::findAndModify</span> — <span class="dc-title">Update a document and return it</span></p>
</div>
<div class="refsect1 description" id="refsect1-mongocollection.findandmodify-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::findAndModify</strong></span>
( <span class="methodparam"><span class="type">array</span> <code class="parameter">$query</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$update</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$fields</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$options</code></span>
]]] )</div>
<p class="para rdfs-comment">
The findAndModify command atomically modifies and returns a single document.
By default, the returned document does not include the modifications made on
the update. To return the document with the modifications made on the
update, use the <var class="varname"><var class="varname">new</var></var> option.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-mongocollection.findandmodify-parameters">
<h3 class="title">Parameters</h3>
<dl>
<dt>
<span class="term"><em><code class="parameter">query</code></em></span>
<dd>
<p class="para">
The query criteria to search for.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">update</code></em></span>
<dd>
<p class="para">
The update criteria.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">fields</code></em></span>
<dd>
<p class="para">
Optionally only return these fields.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">options</code></em></span>
<dd>
<p class="para">
An array of options to apply, such as remove the match document from the
DB and return it.
<table class="doctable informaltable">
<thead>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td><var class="varname"><var class="varname">sort</var></var> <span class="type"><a href="language.types.array.html" class="type array">array</a></span></td>
<td>
Determines which document the operation will modify if the
query selects multiple documents. findAndModify will modify the
first document in the sort order specified by this argument.
</td>
</tr>
<tr>
<td><var class="varname"><var class="varname">remove</var></var> <span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
Optional if <var class="varname"><var class="varname">update</var></var> field exists. When <strong><code>TRUE</code></strong>, removes the selected
document. The default is <strong><code>FALSE</code></strong>.
</td>
</tr>
<tr>
<td><var class="varname"><var class="varname">update</var></var> <span class="type"><a href="language.types.array.html" class="type array">array</a></span></td>
<td>
Optional if <var class="varname"><var class="varname">remove</var></var> field exists.
Performs an update of the selected document.
</td>
</tr>
<tr>
<td><var class="varname"><var class="varname">new</var></var> <span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
Optional. When <strong><code>TRUE</code></strong>, returns the modified document rather than the
original. The findAndModify method ignores the <var class="varname"><var class="varname">new</var></var> option for
remove operations. The default is <strong><code>FALSE</code></strong>.
</td>
</tr>
<tr>
<td><var class="varname"><var class="varname">upsert</var></var> <span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span></td>
<td>
Optional. Used in conjunction with the <var class="varname"><var class="varname">update</var></var> field. When <strong><code>TRUE</code></strong>, the
findAndModify command creates a new document if the query returns
no documents. The default is false. In MongoDB 2.2, the
findAndModify command returns <strong><code>NULL</code></strong> when upsert is <strong><code>TRUE</code></strong>.
</td>
</tr>
<tr>
<td><var class="varname"/></td>
<td>
</td>
</tr>
</tbody>
</table>
</p>
</dd>
</dt>
</dl>
</div>
<div class="refsect1 returnvalues" id="refsect1-mongocollection.findandmodify-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns the original document, or the modified document when
<var class="varname"><var class="varname">new</var></var> is set.
</p>
</div>
<div class="refsect1 errors" id="refsect1-mongocollection.findandmodify-errors">
<h3 class="title">Errors/Exceptions</h3>
<p class="para">
Throws <a href="class.mongoresultexception.html" class="classname">MongoResultException</a> on failure.
</p>
</div>
<div class="refsect1 examples" id="refsect1-mongocollection.findandmodify-examples">
<h3 class="title">Examples</h3>
<div class="example" id="mongocollection.findandmodify.example.basic">
<p><strong>Example #1 <span class="methodname"><strong>MongoCollection::findAndModify()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">Mongo</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$col </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">)-></span><span style="color: #0000BB">jobs</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$col</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(<br /> </span><span style="color: #DD0000">"name" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Next promo"</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"inprogress" </span><span style="color: #007700">=> </span><span style="color: #0000BB">false</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"priority" </span><span style="color: #007700">=> </span><span style="color: #0000BB">0</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"tasks" </span><span style="color: #007700">=> array( </span><span style="color: #DD0000">"select product"</span><span style="color: #007700">, </span><span style="color: #DD0000">"add inventory"</span><span style="color: #007700">, </span><span style="color: #DD0000">"do placement"</span><span style="color: #007700">),<br />) );<br /><br /></span><span style="color: #0000BB">$col</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(<br /> </span><span style="color: #DD0000">"name" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Biz report"</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"inprogress" </span><span style="color: #007700">=> </span><span style="color: #0000BB">false</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"priority" </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"tasks" </span><span style="color: #007700">=> array( </span><span style="color: #DD0000">"run sales report"</span><span style="color: #007700">, </span><span style="color: #DD0000">"email report" </span><span style="color: #007700">)<br />) );<br /><br /></span><span style="color: #0000BB">$col</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(<br /> </span><span style="color: #DD0000">"name" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Biz report"</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"inprogress" </span><span style="color: #007700">=> </span><span style="color: #0000BB">false</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"priority" </span><span style="color: #007700">=> </span><span style="color: #0000BB">2</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"tasks" </span><span style="color: #007700">=> array( </span><span style="color: #DD0000">"run marketing report"</span><span style="color: #007700">, </span><span style="color: #DD0000">"email report" </span><span style="color: #007700">)<br /> ),<br /> array(</span><span style="color: #DD0000">"w" </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">)<br />);<br /><br /><br /><br /></span><span style="color: #0000BB">$retval </span><span style="color: #007700">= </span><span style="color: #0000BB">$col</span><span style="color: #007700">-></span><span style="color: #0000BB">findAndModify</span><span style="color: #007700">(<br /> array(</span><span style="color: #DD0000">"inprogress" </span><span style="color: #007700">=> </span><span style="color: #0000BB">false</span><span style="color: #007700">, </span><span style="color: #DD0000">"name" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Biz report"</span><span style="color: #007700">),<br /> array(</span><span style="color: #DD0000">'$set' </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">'inprogress' </span><span style="color: #007700">=> </span><span style="color: #0000BB">true</span><span style="color: #007700">, </span><span style="color: #DD0000">"started" </span><span style="color: #007700">=> new </span><span style="color: #0000BB">MongoDate</span><span style="color: #007700">())),<br /> </span><span style="color: #0000BB">null</span><span style="color: #007700">,<br /> array(<br /> </span><span style="color: #DD0000">"sort" </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">"priority" </span><span style="color: #007700">=> -</span><span style="color: #0000BB">1</span><span style="color: #007700">),<br /> </span><span style="color: #DD0000">"new" </span><span style="color: #007700">=> </span><span style="color: #0000BB">true</span><span style="color: #007700">,<br /> )<br />);<br /><br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$retval</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
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
array(6) {
["_id"]=>
object(MongoId)#7 (1) {
["$id"]=>
string(24) "5091b5b244415e8cc3000002"
}
["inprogress"]=>
bool(true)
["name"]=>
string(10) "Biz report"
["priority"]=>
int(2)
["started"]=>
object(MongoDate)#8 (2) {
["sec"]=>
int(1351726514)
["usec"]=>
int(925000)
}
["tasks"]=>
array(2) {
[0]=>
string(20) "run marketing report"
[1]=>
string(12) "email report"
}
}
</pre></div>
</div>
</div>
<div class="example" id="mongocollection.findandmodify.example.error">
<p><strong>Example #2 <span class="methodname"><strong>MongoCollection::findAndModify()</strong></span> error handling</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$m </span><span style="color: #007700">= new </span><span style="color: #0000BB">Mongo</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$col </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">)-></span><span style="color: #0000BB">jobs</span><span style="color: #007700">;<br />try {<br /> </span><span style="color: #0000BB">$retval </span><span style="color: #007700">= </span><span style="color: #0000BB">$col</span><span style="color: #007700">-></span><span style="color: #0000BB">findAndModify</span><span style="color: #007700">(<br /> array(</span><span style="color: #DD0000">"inprogress" </span><span style="color: #007700">=> </span><span style="color: #0000BB">false</span><span style="color: #007700">, </span><span style="color: #DD0000">"name" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Next promo"</span><span style="color: #007700">),<br /> array(</span><span style="color: #DD0000">'$pop' </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">"tasks" </span><span style="color: #007700">=> -</span><span style="color: #0000BB">1</span><span style="color: #007700">)),<br /> array(</span><span style="color: #DD0000">"tasks" </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">'$pop' </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">"stuff"</span><span style="color: #007700">))),<br /> array(</span><span style="color: #DD0000">"new" </span><span style="color: #007700">=> </span><span style="color: #0000BB">true</span><span style="color: #007700">)<br /> );<br />} catch(</span><span style="color: #0000BB">MongoResultException $e</span><span style="color: #007700">) {<br /> echo </span><span style="color: #0000BB">$e</span><span style="color: #007700">-></span><span style="color: #0000BB">getCode</span><span style="color: #007700">(), </span><span style="color: #DD0000">" : "</span><span style="color: #007700">, </span><span style="color: #0000BB">$e</span><span style="color: #007700">-></span><span style="color: #0000BB">getMessage</span><span style="color: #007700">(), </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$e</span><span style="color: #007700">-></span><span style="color: #0000BB">getDocument</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
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
13097 : exception: Unsupported projection option: $pop
array(3) {
["errmsg"]=>
string(46) "exception: Unsupported projection option: $pop"
["code"]=>
int(13097)
["ok"]=>
float(0)
}
</pre></div>
</div>
</div>
</div>
<div class="refsect1 seealso" id="refsect1-mongocollection.findandmodify-seealso">
<h3 class="title">See Also</h3>
<ul class="simplelist">
<li class="member">The MongoDB <a href="http://docs.mongodb.org/manual/reference/command/findAndModify/" class="link external">» findAndModify command</a> docs</li>
</ul>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongocollection.find.html">MongoCollection::find</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongocollection.findone.html">MongoCollection::findOne</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>
