<!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="warning"><strong class="warning">Warning</strong> <p class="para">This extension that defines this class is deprecated. Instead, the <a href="set.mongodb.html" class="link">MongoDB</a> extension should be used. There is no equivalent for this class in the new extension.</p> <p class="para"> The concept of database references, and hence this class, has been deprecated in the database. </p> </div> <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-1654"> <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-1655"> <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="https://docs.mongodb.com/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>