<!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>The MongoDBRef class</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongoint64.tostring.html">MongoInt64::__toString</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongodbref.create.html">MongoDBRef::create</a></div>
<div class="up"><a href="mongo.types.html">Types</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="class.mongodbref" class="reference">
<h1 class="title">The MongoDBRef class</h1>
<div class="partintro"><p class="verinfo">(PECL mongo >=0.9.0)</p>
<div class="section" id="mongodbref.intro">
<h2 class="title">Introduction</h2>
<p class="para">
This class can be used to create lightweight links between objects in
different collections.
</p>
<p class="para">
<em class="emphasis">Motivation</em>: Suppose we need to refer to a document in
another collection. The easiest way is to create a field in the current
document. For example, if we had a "people" collection and an "addresses"
collection, we might want to create a link between each person document and
an address document:
<div class="example" id="example-1501">
<p><strong>Example #1 Linking documents</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$people </span><span style="color: #007700">= </span><span style="color: #0000BB">$db</span><span style="color: #007700">-></span><span style="color: #0000BB">people</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$addresses </span><span style="color: #007700">= </span><span style="color: #0000BB">$db</span><span style="color: #007700">-></span><span style="color: #0000BB">addresses</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$myAddress </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"line 1" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"123 Main Street"</span><span style="color: #007700">, <br /> </span><span style="color: #DD0000">"line 2" </span><span style="color: #007700">=> </span><span style="color: #0000BB">null</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"city" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Springfield"</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"state" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Vermont"</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"country" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"USA"</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// save the address<br /></span><span style="color: #0000BB">$addresses</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$myAddress</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// save a person with a reference to the address<br /></span><span style="color: #0000BB">$me </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"name" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Fred"</span><span style="color: #007700">, </span><span style="color: #DD0000">"address" </span><span style="color: #007700">=> </span><span style="color: #0000BB">$myAddress</span><span style="color: #007700">[</span><span style="color: #DD0000">'_id'</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">$people</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$me</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
Then, later on, we can find the person's address by querying the "addresses"
collection with the <a href="class.mongoid.html" class="classname">MongoId</a> we saved in the "people"
collection.
</p>
<p class="para">
Suppose now that we have a more general case, where we don't know which
collection (or even which database) contains the referenced document.
<strong class="classname">MongoDBRef</strong> is a good choice for this case, as it is a
common format that all of the drivers and the database understand.
</p>
<p class="para">
If each person had a list of things they liked which could come from
multiple collections, such as "hobbies", "sports", "books", etc., we could
use <strong class="classname">MongoDBRef</strong>s to keep track of what "like" went
with what collection:
<div class="example" id="example-1502">
<p><strong>Example #2 Creating MongoDBRef links</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$people </span><span style="color: #007700">= </span><span style="color: #0000BB">$db</span><span style="color: #007700">-></span><span style="color: #0000BB">selectCollection</span><span style="color: #007700">(</span><span style="color: #DD0000">"people"</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// model trains are in the "hobbies" collection<br /></span><span style="color: #0000BB">$trainRef </span><span style="color: #007700">= </span><span style="color: #0000BB">MongoDBRef</span><span style="color: #007700">::</span><span style="color: #0000BB">create</span><span style="color: #007700">(</span><span style="color: #DD0000">"hobbies"</span><span style="color: #007700">, </span><span style="color: #0000BB">$modelTrains</span><span style="color: #007700">[</span><span style="color: #DD0000">'_id'</span><span style="color: #007700">]);<br /></span><span style="color: #FF8000">// soccer is in the "sports" collection<br /></span><span style="color: #0000BB">$soccerRef </span><span style="color: #007700">= </span><span style="color: #0000BB">MongoDBRef</span><span style="color: #007700">::</span><span style="color: #0000BB">create</span><span style="color: #007700">(</span><span style="color: #DD0000">"sports"</span><span style="color: #007700">, </span><span style="color: #0000BB">$soccer</span><span style="color: #007700">[</span><span style="color: #DD0000">'_id'</span><span style="color: #007700">]);<br /><br /></span><span style="color: #FF8000">// now we'll know what collections the items in the "likes" array came from when<br />// we retrieve this document<br /></span><span style="color: #0000BB">$people</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"name" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"Fred"</span><span style="color: #007700">, </span><span style="color: #DD0000">"likes" </span><span style="color: #007700">=> array(</span><span style="color: #0000BB">$trainRef</span><span style="color: #007700">, </span><span style="color: #0000BB">$soccerRef</span><span style="color: #007700">)));<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
Database references can be thought of as hyperlinks: they give the unique
address of another document, but they do not load it or automatically follow
the link/reference.
</p>
<p class="para">
A database reference is just a normal associative array, not an instance of
<strong class="classname">MongoDBRef</strong>, so this class is a little different than
the other data type classes. This class contains exclusively static methods
for manipulating database references.
</p>
</div>
<div class="section" id="mongodbref.synopsis">
<h2 class="title">Class synopsis</h2>
<div class="classsynopsis">
<div class="ooclass"></div>
<div class="classsynopsisinfo">
<span class="ooclass">
<strong class="classname">MongoDBRef</strong>
</span>
{</div>
<div class="classsynopsisinfo classsynopsisinfo_comment">/* Methods */</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="modifier">static</span> <span class="type">array</span> <span class="methodname"><a href="mongodbref.create.html" class="methodname">create</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$collection</code></span>
, <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$id</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$database</code></span>
] )</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="modifier">static</span> <span class="type">array</span> <span class="methodname"><a href="mongodbref.get.html" class="methodname">get</a></span>
( <span class="methodparam"><span class="type"><a href="class.mongodb.html" class="type MongoDB">MongoDB</a></span> <code class="parameter">$db</code></span>
, <span class="methodparam"><span class="type">array</span> <code class="parameter">$ref</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="modifier">static</span> <span class="type">bool</span> <span class="methodname"><a href="mongodbref.isref.html" class="methodname">isRef</a></span>
( <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$ref</code></span>
)</div>
}</div>
</div>
<div class="section">
<h2 class="title">See Also</h2>
<p class="para">
MongoDB core docs on <a href="http://docs.mongodb.org/manual/reference/database-references/" class="link external">» databases references</a>.
</p>
</div>
</div>
<h2>Table of Contents</h2><ul class="chunklist chunklist_reference"><li><a href="mongodbref.create.html">MongoDBRef::create</a> — Creates a new database reference</li><li><a href="mongodbref.get.html">MongoDBRef::get</a> — Fetches the object pointed to by a reference</li><li><a href="mongodbref.isref.html">MongoDBRef::isRef</a> — Checks if an array is a database reference</li></ul>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongoint64.tostring.html">MongoInt64::__toString</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongodbref.create.html">MongoDBRef::create</a></div>
<div class="up"><a href="mongo.types.html">Types</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
