<!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>Updates</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongo.queries.html">Querying</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongo.security.html">Security</a></div>
<div class="up"><a href="mongo.manual.html">Manual</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongo.updates" class="chapter">
<h1>Updates</h1>
<p class="para">
Updates can be one of the most complicated operation available with
MongoDB. They combine a query with an action, modifying documents that match
the criteria. They are also extremely powerful, allowing you to change
documents quickly and replace them altogether. They are done in-place (when
possible) with little overhead.
</p>
<div class="section">
<h2 class="title">Modifying vs. replacing documents</h2>
<p class="para">
There are two types of updates you can use: modifying updates and replacing
updates. Modifying updates contain $-operators and change fields in a
document: they might increment counters, push new elements onto an array,
or change the type of a field.
</p>
<p class="para">
For example, a modifying update could add a new field to a document.
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/** suppose documents look like:<br /> * {"username" : "...", "password" : "...", "email" : "..."}<br /> */<br /></span><span style="color: #0000BB">$coll</span><span style="color: #007700">-></span><span style="color: #0000BB">update</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"joe"</span><span style="color: #007700">), array(</span><span style="color: #DD0000">'$set' </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">"twitter" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"@joe4153"</span><span style="color: #007700">)));<br /><br /></span><span style="color: #FF8000">/** now the document will look like:<br /> * {"username" : "joe", "password" : "...", "email" : "...", "twitter" : "@joe4153"}<br /> */<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</p>
<p class="para">
Replacing updates replace the entire matching document with a new document.
They are generally not as efficient as using $-modifiers, but can be very
usefully for complex operations or updates that can't be expressed in terms
of $-operators.
</p>
<p class="para">
For example, a replacing update can completely change the structure of a
document.
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/** suppose documents look like:<br /> * {"username" : "...", "password" : "...", "email" : "..."}<br /> */<br /></span><span style="color: #0000BB">$coll</span><span style="color: #007700">-></span><span style="color: #0000BB">update</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"joe"</span><span style="color: #007700">), array(</span><span style="color: #DD0000">"userId" </span><span style="color: #007700">=> </span><span style="color: #0000BB">12345</span><span style="color: #007700">, </span><span style="color: #DD0000">"info" </span><span style="color: #007700">=> array(<br /> </span><span style="color: #DD0000">"name" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"joe"</span><span style="color: #007700">, </span><span style="color: #DD0000">"twitter" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"@joe4153"</span><span style="color: #007700">, </span><span style="color: #DD0000">"email" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"..."</span><span style="color: #007700">), </span><span style="color: #DD0000">"likes" </span><span style="color: #007700">=> array()));<br /><br /></span><span style="color: #FF8000">/** now the document will look like:<br /> * {<br /> * "userId" : 12345, <br /> * "info" : {<br /> * "name" : "joe", <br /> * "twitter" : "@joe4153", <br /> * "email" : "..."<br /> * },<br /> * "likes" : []<br /> * }<br /> */<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</p>
</div>
<div class="section">
<h2 class="title">Updating Nested Objects</h2>
<p class="para">
Suppose we wish to change the name of a comment's author in this document:
<div class="example-contents">
<div class="cdata"><pre>
{
"_id" : ObjectId("4b06c282edb87a281e09dad9"),
"content" : "this is a blog post.",
"comments" :
[
{
"author" : "Mike",
"comment" : "I think that blah blah blah...",
},
{
"author" : "John",
"comment" : "I disagree."
}
]
}
</pre></div>
</div>
In order to change an inner field, we use $set (so that all of the other
fields are not removed!) with the index of comment to change:
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$blog</span><span style="color: #007700">-></span><span style="color: #0000BB">update</span><span style="color: #007700">(</span><span style="color: #0000BB">$criteria</span><span style="color: #007700">, array(</span><span style="color: #DD0000">'$set' </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">"comments.1" </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">"author" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Jim"</span><span style="color: #007700">))));<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</p>
</div>
<div class="section">
<h2 class="title">The Positional Operator</h2>
<p class="para">
The positional operator <em>$</em> is useful for updating objects
that are in arrays. In the example above, for instance, suppose that we did
not know the index of the comment that we needed to change, merely that we
needed to change "John" to "Jim". We can use <em>$</em> to do so.
</p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$blog</span><span style="color: #007700">-></span><span style="color: #0000BB">update</span><span style="color: #007700">(<br /> array(</span><span style="color: #DD0000">"comments.author" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"John"</span><span style="color: #007700">), <br /> array(</span><span style="color: #DD0000">'$set' </span><span style="color: #007700">=> array(</span><span style="color: #DD0000">'comments.$.author' </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Jim"</span><span style="color: #007700">)));<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongo.queries.html">Querying</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongo.security.html">Security</a></div>
<div class="up"><a href="mongo.manual.html">Manual</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
