<!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>Types</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongocursor.valid.html">MongoCursor::valid</a></div>
<div class="next" style="text-align: right; float: right;"><a href="class.mongoid.html">MongoId</a></div>
<div class="up"><a href="book.mongo.html">Mongo</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongo.types" class="part">
<h1>Types</h1>
<h2>Table of Contents</h2><ul class="chunklist chunklist_part"><li><a href="class.mongoid.html">MongoId</a></li><li><a href="class.mongocode.html">MongoCode</a></li><li><a href="class.mongodate.html">MongoDate</a></li><li><a href="class.mongoregex.html">MongoRegex</a></li><li><a href="class.mongobindata.html">MongoBinData</a></li><li><a href="class.mongoint32.html">MongoInt32</a></li><li><a href="class.mongoint64.html">MongoInt64</a></li><li><a href="class.mongodbref.html">MongoDBRef</a></li><li><a href="class.mongominkey.html">MongoMinKey</a></li><li><a href="class.mongomaxkey.html">MongoMaxKey</a></li><li><a href="class.mongotimestamp.html">MongoTimestamp</a></li></ul>
<div class="partintro">
<div class="section">
<p class="para">
MongoDB allows programmers to save and query for data expressed in all of the
basic PHP types, compound types (arrays, associative arrays, and objects), and
a half-dozen classes provided by the MongoDB PHP driver (for regular
expressions, dates, and other specialized applications).
</p>
</div>
<div class="section">
<h2 class="title">Booleans and <strong><code>NULL</code></strong></h2>
<p class="para">
<strong><code>TRUE</code></strong>, <strong><code>FALSE</code></strong>, and <strong><code>NULL</code></strong> can be used as-is.
</p>
</div>
<div class="section">
<h2 class="title">Numbers</h2>
<p class="para">
Numbers are distinct from strings in MongoDB: "123" does not match 123.
Thus, if you want to make sure numbers are sorted and matched correctly, you
must make sure that they are actually saved as numbers.
</p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$doc </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"a" </span><span style="color: #007700">=> </span><span style="color: #0000BB">123</span><span style="color: #007700">, </span><span style="color: #DD0000">"b" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"123"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$doc</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$doc</span><span style="color: #007700">-></span><span style="color: #0000BB">find</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"a" </span><span style="color: #007700">=> </span><span style="color: #0000BB">123</span><span style="color: #007700">)); </span><span style="color: #FF8000">// matches<br /></span><span style="color: #0000BB">$doc</span><span style="color: #007700">-></span><span style="color: #0000BB">find</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"a" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"123"</span><span style="color: #007700">)); </span><span style="color: #FF8000">// doesn't match<br /></span><span style="color: #0000BB">$doc</span><span style="color: #007700">-></span><span style="color: #0000BB">find</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"a" </span><span style="color: #007700">=> </span><span style="color: #0000BB">123.0</span><span style="color: #007700">)); </span><span style="color: #FF8000">// matches<br /></span><span style="color: #0000BB">$doc</span><span style="color: #007700">-></span><span style="color: #0000BB">find</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"b" </span><span style="color: #007700">=> </span><span style="color: #0000BB">123</span><span style="color: #007700">)); </span><span style="color: #FF8000">// doesn't match<br /></span><span style="color: #0000BB">$doc</span><span style="color: #007700">-></span><span style="color: #0000BB">find</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"b" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"123"</span><span style="color: #007700">)); </span><span style="color: #FF8000">// matches<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<p class="para">
As noted above, floating point numbers do compare with/match integer numbers
as one would expect.
</p>
<div class="section">
<h2 class="title">Large Numbers</h2>
<p class="para">
By default, on a 32-bit system, numbers are sent to the database as 32-bit
integers. On a 64-bit system, they are sent as 64-bit integers. For
backwards compatibility, all systems deserialize 64-bit integers as floating
point numbers. Floating point numbers are not exact. If you need exact
values, you must tweak your
<a href="mongo.configure;" class="link external">» php.ini settings</a>.
</p>
<p class="para">
On a 32-bit system, if <em>mongo.long_as_object</em> is set,
64-bit integers will be returns as <a href="class.mongoint64.html" class="classname">MongoInt64</a>
objects. The integer will be stored in the <em>value</em> field
with perfect precision (as a string). You can also use
<a href="class.mongoint64.html" class="classname">MongoInt64</a> to save 64-bit integers on 32-bit
machines.
</p>
<p class="para">
On 64-bit systems, you can either set <em>mongo.long_as_object</em>
or set <em>mongo.native_long</em>.
<em>mongo.native_long</em> will return 64-bit integers and
"normal" PHP integers. You can use <a href="class.mongoint32.html" class="classname">MongoInt32</a> to
save 32-bit integers on 64-bit machines.
</p>
<p class="para">
You should set the <em>mongo.long_as_object</em> and
<em>mongo.native_long</em> behavior that you plan to use, even if
it is the default behavior (to protect against future changes to the
defaults).
</p>
<p class="para">
See also: <a href="mongo.configure;" class="link external">» php.ini Options</a>,
<a href="class.mongoint32.html" class="classname">MongoInt32</a>, <a href="class.mongoint64.html" class="classname">MongoInt64</a>.
</p>
</div>
</div>
<div class="section">
<h2 class="title">Strings</h2>
<p class="para">
Strings must be UTF-8. Non-UTF-8 strings must either be converted to UTF-8
before being sent to the database or saved as binary data.
</p>
<p class="para">
Regular expressions can be used to match strings, and are expressed using the
<a href="class.mongoregex.html" class="classname">MongoRegex</a> class.
</p>
</div>
<div class="section">
<h2 class="title">Binary Data</h2>
<p class="para">
Non-UTF-8 strings, images, and any other binary data should be sent to the
database using the <a href="class.mongobindata.html" class="classname">MongoBinData</a> type.
</p>
</div>
<div class="section">
<h2 class="title">Dates</h2>
<p class="para">
Dates can be created using the <a href="class.mongodate.html" class="classname">MongoDate</a> class. They
are stored as milliseconds since the epoch.
</p>
<p class="para">
<a href="class.mongotimestamp.html" class="classname">MongoTimestamp</a> is not for saving dates or timestamps,
it is used internally by MongoDB. Unless you are creating a tool that
interacts with the internals of replication or sharding, you should use
<a href="class.mongodate.html" class="classname">MongoDate</a>, <em class="emphasis">not</em>
<a href="class.mongotimestamp.html" class="classname">MongoTimestamp</a>.
</p>
</div>
<div class="section">
<h2 class="title">Unique Ids</h2>
<p class="para">
The driver will automatically create an <em>_id</em> field before
inserting a document (unless one is specified by the user). This field is an
instance of <a href="class.mongoid.html" class="classname">MongoId</a> (called "ObjectId" in most other
languages).
</p>
<p class="para">
These ids are 12 bytes long and composed of:
<ul class="itemizedlist">
<li class="listitem">
<p class="para">4 bytes of timestamp</p>
<p class="para">
No two records can have the same id if they were inserted at different
times.
</p>
</li>
<li class="listitem">
<p class="para">3 bytes machine id</p>
<p class="para">
No two records can have the same id if they were inserted on different
machines
</p>
</li>
<li class="listitem">
<p class="para">2 bytes thread id</p>
<p class="para">
No two records can have the same id if they were inserted by different
threads running on the same machine.
</p>
</li>
<li class="listitem">
<p class="para">3 bytes incrementing value</p>
<p class="para">
Each time an id is created, a global counter is incremented and used
as the increment value of the next id.
</p>
</li>
</ul>
Thus, no two records can have the same id unless a single process on a
single machine managed to insert 256^3 (over 16 million) documents in
one second, overflowing the increment field.
</p>
</div>
<div class="section">
<h2 class="title">JavaScript</h2>
<p class="para">
MongoDB comes with a JavaScript engine, so you can embed JavaScript in
queries (using a $where clause), send it directly to the database to be
executed, and use it to perform aggregations.
</p>
<p class="para">
For security, use <a href="class.mongocode.html" class="classname">MongoCode</a>'s <em>scope</em>
field to use PHP variables in JavaScript. Code that does not require
external values can either use <a href="class.mongocode.html" class="classname">MongoCode</a> or just be
a string. See the
<a href="mongo.security;" class="link external">» section on security</a> for more
information about sending JavaScript to the database.
</p>
</div>
<div class="section">
<h2 class="title">Arrays and Objects</h2>
<p class="para">
Arrays and objects can also be saved to the database. An array with ascending
numeric keys will be saved as a an array, anything else will be saved as an
object.
</p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000">// $scores will be saved as an array<br /></span><span style="color: #0000BB">$scores </span><span style="color: #007700">= array(</span><span style="color: #0000BB">98</span><span style="color: #007700">, </span><span style="color: #0000BB">100</span><span style="color: #007700">, </span><span style="color: #0000BB">73</span><span style="color: #007700">, </span><span style="color: #0000BB">85</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"scores" </span><span style="color: #007700">=> </span><span style="color: #0000BB">$scores</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">// $scores will be saved as an object<br /></span><span style="color: #0000BB">$scores </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"quiz1" </span><span style="color: #007700">=> </span><span style="color: #0000BB">98</span><span style="color: #007700">, </span><span style="color: #DD0000">"midterm" </span><span style="color: #007700">=> </span><span style="color: #0000BB">100</span><span style="color: #007700">, </span><span style="color: #DD0000">"quiz2" </span><span style="color: #007700">=> </span><span style="color: #0000BB">73</span><span style="color: #007700">, </span><span style="color: #DD0000">"final" </span><span style="color: #007700">=> </span><span style="color: #0000BB">85</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"scores" </span><span style="color: #007700">=> </span><span style="color: #0000BB">$scores</span><span style="color: #007700">));<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<p class="para">
If you query for these objects using the database shell, they will look like:
<div class="example-contents">
<div class="cdata"><pre>
> db.students.find()
{ "_id" : ObjectId("4b06beada9ad6390dab17c43"), "scores" : [ 98, 100, 73, 85 ] }
{ "_id" : ObjectId("4b06bebea9ad6390dab17c44"), "scores" : { "quiz1" : 98, "midterm" : 100, "quiz2" : 73, "final" : 85 } }
</pre></div>
</div>
</p>
<p class="para">
The database can also save arbitrary PHP objects (although they will be
returned as associative arrays). The fields are used for the key/value
pairs. For example, a blog post might look like:
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /> </span><span style="color: #FF8000">// the blog post class<br /> </span><span style="color: #007700">class </span><span style="color: #0000BB">Post </span><span style="color: #007700">{<br /><br /> var </span><span style="color: #0000BB">$author</span><span style="color: #007700">;<br /> var </span><span style="color: #0000BB">$content</span><span style="color: #007700">;<br /> var </span><span style="color: #0000BB">$comments </span><span style="color: #007700">= array();<br /> var </span><span style="color: #0000BB">$date</span><span style="color: #007700">;<br /><br /> public function </span><span style="color: #0000BB">__construct</span><span style="color: #007700">(</span><span style="color: #0000BB">$author</span><span style="color: #007700">, </span><span style="color: #0000BB">$content</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">author </span><span style="color: #007700">= </span><span style="color: #0000BB">$author</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">content </span><span style="color: #007700">= </span><span style="color: #0000BB">$content</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">date </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoDate</span><span style="color: #007700">();<br /> }<br /><br /> public function </span><span style="color: #0000BB">setTitle</span><span style="color: #007700">(</span><span style="color: #0000BB">$title</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">title </span><span style="color: #007700">= </span><span style="color: #0000BB">$title</span><span style="color: #007700">;<br /> }<br />}<br /><br /></span><span style="color: #FF8000">// create a simple blog post and insert it into the database<br /></span><span style="color: #0000BB">$post1 </span><span style="color: #007700">= new </span><span style="color: #0000BB">Post</span><span style="color: #007700">(</span><span style="color: #DD0000">"Adam"</span><span style="color: #007700">, </span><span style="color: #DD0000">"This is a blog post"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$blog</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$post1</span><span style="color: #007700">);<br /><br /><br /></span><span style="color: #FF8000">// there is nothing restricting the type of the "author" field, so we can make<br />// it a nested object<br /></span><span style="color: #0000BB">$author </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">"karma" </span><span style="color: #007700">=> </span><span style="color: #0000BB">42</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$post2 </span><span style="color: #007700">= new </span><span style="color: #0000BB">Post</span><span style="color: #007700">(</span><span style="color: #0000BB">$author</span><span style="color: #007700">, </span><span style="color: #DD0000">"This is another blog post."</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// we create an extra field by setting the title<br /></span><span style="color: #0000BB">$post2</span><span style="color: #007700">-></span><span style="color: #0000BB">setTitle</span><span style="color: #007700">(</span><span style="color: #DD0000">"Second Post"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$blog</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$post2</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</p>
<p class="para">
From the database shell, this will look something like:
<div class="example-contents">
<div class="cdata"><pre>
> db.blog.find()
{ "_id" : ObjectId("4b06c263edb87a281e09dad8"), "author" : "Adam", "content" : "This is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:22:59 GMT-0500 (EST)" }
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "author" : { "name" : "Fred", "karma" : 42 }, "content" : "This is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:23:30 GMT-0500 (EST)", "title" : "Second Post" }
</pre></div>
</div>
</p>
<p class="para">
The driver will not detect reference loops in arrays and objects. For
example, this will give a fatal error:
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$GLOBALS</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents">
<div class="cdata"><pre>
Fatal error: Nesting level too deep - recursive dependency?
</pre></div>
</div>
If you need to insert documents that may have recursive dependency, you have
to check for it yourself before passing it to the driver.
</p>
</div>
</div>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongocursor.valid.html">MongoCursor::valid</a></div>
<div class="next" style="text-align: right; float: right;"><a href="class.mongoid.html">MongoId</a></div>
<div class="up"><a href="book.mongo.html">Mongo</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
