Source of: /manual/en/class.mongodbref.php
<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/book.mongo.inc";
$setup = array (
'home' =>
array (
0 => 'index.php',
1 => 'PHP Manual',
),
'head' =>
array (
0 => 'UTF-8',
1 => 'en',
),
'this' =>
array (
0 => 'class.mongodbref.php',
1 => 'MongoDBRef',
),
'up' =>
array (
0 => 'book.mongo.php',
1 => 'Mongo',
),
'prev' =>
array (
0 => 'mongobindata.tostring.php',
1 => 'MongoBinData::__toString',
),
'next' =>
array (
0 => 'mongodbref.create.php',
1 => 'MongoDBRef::create',
),
);
$setup["toc"] = $TOC;
$setup["parents"] = $PARENTS;
manual_setup($setup);
manual_header();
?>
<div>
<h1 class="title">The MongoDBRef class</h1>
<div class="partintro">
<div id="mongodbref.intro" class="section">
<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
and address document:
</p><div class="example-contents programlisting">
<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 /></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">selectCollection</span><span style="color: #007700">(</span><span style="color: #DD0000">"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>
<p>
</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.php" 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.
<b class="classname">MongoDBRef</b> 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 <b class="classname">MongoDBRef</b>s to keep track of what "like" went
with what collection:
</p><div class="example-contents programlisting">
<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>
<p>
</p>
</div>
<div id="mongodbref.synopsis" class="section">
<h2 class="title">Class synopsis</h2>
<div class="classsynopsis">
<div class="ooclass"><b class="classname">MongoDBRef</b></div>
<div class="classsynopsisinfo">
<span class="ooclass">
<b class="classname">MongoDBRef</b>
</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.php" class="function">create</a></span>
( <span class="methodparam"><span class="type">string</span> <tt class="parameter">$collection</tt></span>
, <span class="methodparam"><span class="type"><a href="language.pseudo-types.php#language.types.mixed" class="type mixed">mixed</a></span> <tt class="parameter">$id</tt></span>
[, <span class="methodparam"><span class="type">string</span> <tt class="parameter">$database</tt></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.php" class="function">get</a></span>
( <span class="methodparam"><span class="type"><a href="class.mongodb.php" class="type MongoDB">MongoDB</a></span> <tt class="parameter">$db</tt></span>
, <span class="methodparam"><span class="type">array</span> <tt class="parameter">$ref</tt></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="modifier">static</span> <span class="type">boolean</span> <span class="methodname"><a href="mongodbref.isref.php" class="function">isRef</a></span>
( <span class="methodparam"><span class="type"><a href="language.pseudo-types.php#language.types.mixed" class="type mixed">mixed</a></span> <tt class="parameter">$ref</tt></span>
)</div>
}</div>
</div>
</div>
<h2>Table of Contents</h2><ul class="chunklist chunklist_reference"><li><a href="mongodbref.create.php">MongoDBRef::create</a> — Creates a new database reference</li><li><a href="mongodbref.get.php">MongoDBRef::get</a> — Fetches the object pointed to by a reference</li><li><a href="mongodbref.isref.php">MongoDBRef::isRef</a> — Checks if an array is a database reference</li></ul>
</div>
<?php manual_footer(); ?>
