Types
Table of Contents
- MongoId
- MongoCode
- MongoDate
- MongoRegex
- MongoBinData
- MongoInt32
- MongoInt64
- MongoDBRef
- MongoMinKey
- MongoMaxKey
- MongoTimestamp
Change in number handling
The default behavior for numbers will be changing in version 1.1.0. For most programmers, this will make the driver's numeric handling smoother and more natural, but it may require updating application code to work.
The backwards-breaking changes will be related to the serialization and deserialization of integers. You can test how these changes will affect your code by specifying the .ini changes now: mongo.native_int and mongo.long_as_object will default to TRUE.
Serialization: by default pre-1.1.0, all PHP integers are serialized as 32-bit integers, even on 64-bit machines. This means that large numbers get silently truncated. In 1.1.0, 64-bit machines will, by default, save integers as 64-bit integers. 32-bit machines will continue to save integers as 32-bit integers (you can also use the MongoInt32 and MongoInt64 classes to use 32-bit int on a 64-bit machine or visa versa).
Deserialization: by default pre-1.1.0, 64-bit integers will be deserialized as doubles. This is not a perfect mapped and means they will be resaved as the wrong type (double instead of 64-bit integer). In 1.1.0, 64-bit integers will be returned as MongoInt64's on 32-bit machines.
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).
Simple Types
The built-in types are:
| Type | Description | Size in MongoDB (bytes) |
|---|---|---|
| NULL | Fairly self-explanatory. | 0 |
| boolean | TRUE and FALSE | 1 |
| int | Integer values. | 4 |
| float | Double values. | 8 |
| string | Strings of UTF-8 characters. | string length + 1 |
Arrays and Objects
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.
<?php
// $scores will be saved as an array
$scores = array(98, 100, 73, 85);
$collection->insert(array("scores" => $scores));
// $scores will be saved as an object
$scores = array("quiz1" => 98, "midterm" => 100, "quiz2" => 73, "final" => 85);
$collection->insert(array("scores" => $scores));
?>
If you query for these objects using the database shell, they will look like:
> db.students.find()
{ "_id" : ObjectId("4b06beada9ad6390dab17c43"), "scores" : [ 98, 100, 73, 85 ] }
{ "_id" : ObjectId("4b06bebea9ad6390dab17c44"), "scores" : { "quiz1" : 98, "midterm" : 100, "quiz2" : 73, "final" : 85 } }
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:
<?php
// the blog post class
class Post {
var $author;
var $content;
var $comments = array();
var $date;
public function __construct($author, $content) {
$this->author = $author;
$this->content = $content;
$this->date = new MongoDate();
}
public function setTitle($title) {
$this->title = $title;
}
}
// create a simple blog post and insert it into the database
$post1 = new Post("Adam", "This is a blog post");
$blog->insert($post1);
// there is nothing restricting the type of the "author" field, so we can make
// it a nested object
$author = array("name" => "Fred", "karma" => 42);
$post2 = new Post($author, "This is another blog post.");
// we create an extra field by setting the title
$post2->setTitle("Second Post");
$blog->insert($post2);
?>
From the database shell, this will look something like:
> 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" }
The driver will not detect reference loops in arrays and objects. For example, this will give a fatal error:
<?php
$collection->insert($GLOBALS);
?>
Fatal error: Nesting level too deep - recursive dependency?
MongoDB Types
The Mongo PHP driver also defines a few new types to use with the database. See class documentation for details and examples.
| Type | Description | Size in MongoDB (bytes) |
|---|---|---|
| MongoBinData | Binary data. | Number of bytes in binary data + 5 |
| MongoCode | JavaScript code. | String length of code + object size of scope. |
| MongoDate | Dates and times. Stored as milliseconds since the epoch. | 8 |
| MongoId | Unique document id:
|
12 |
| MongoMinKey | Always smaller than any other value. | String length of code + object size of scope. |
| MongoMaxKey | JavaScript code. | Always larger than any other value. |
| MongoRegex | Regular expressions. | Number of characters in regular expression + number of flags |
| MongoTimestamp | Replication timestamp | 8 |
BSON
MongoDB uses a storage format called "BSON," Binary Serializable Object Notation, which is similar to JSON but more compact and rich in types. Listed below is the exact byte size of each type (or information required to compute its size, in the case of variable-length types). Keep in mind that these sizes do not include field names. The size of an object can be manually computed, but it may be easier for programmers to call the bson_encode() function and take the length of the resulting string.
An example of manually computing BSON size for saving the object array("x" => null, "y" => 40):
4 bytes (object size)
1 byte (type of "x" field)
2 bytes ("x" and "\0")
0 bytes (for null)
1 byte (type of "y" field)
2 bytes ("y" and "\0")
4 bytes (for an integer)
1 byte (end-of-object byte)
-----------------------
15 bytes