- Reference >
- BSON
BSON
Overview
MongoDB stores data records as BSON documents. BSON is a binary representation of JSON documents, though it contains more data types than JSON. For the BSON spec, see bsonspec.org.
By default, the MongoDB PHP Library returns BSON documents as
MongoDB\Model\BSONDocument
objects and BSON arrays as
MongoDB\Model\BSONArray
objects, respectively.
BSON Classes
-
MongoDB\Model\BSONArray
This class extends PHP’s ArrayObject class. It also implements PHP’s JsonSerializable interface and the driver’s MongoDB\BSON\Serializable and MongoDB\BSON\Unserializable interfaces.
By default, the library will deserialize BSON arrays as instances of this class. During BSON and JSON serialization, instances of this class will serialize as an array type (array_values() is used internally to numerically reindex the array).
-
MongoDB\Model\BSONDocument
This class extends PHP’s ArrayObject class. It also implements PHP’s JsonSerializable interface and the driver’s MongoDB\BSON\Serializable and MongoDB\BSON\Unserializable interfaces.
By default, the library will deserialize BSON documents as instances of this class. During BSON and JSON serialization, instances of this class will serialize as a document type (object casting is used internally).
Type Maps
Most methods that read data from MongoDB support a typeMap
option, which
allows control over how BSON is converted to PHP. Additionally,
the MongoDB\Client
, MongoDB\Database
, and
MongoDB\Collection
classes accept a typeMap
option, which can
be used to specify a default type map to apply to any supporting methods and
selected classes (e.g. MongoDB\Client::selectDatabase()
).
The MongoDB\Client
, MongoDB\Database
, and
MongoDB\Collection
classes use the following type map by
default:
The type map above will convert BSON documents and arrays to
MongoDB\Model\BSONDocument
and
MongoDB\Model\BSONArray
objects, respectively. The root
and
document
keys are used to distinguish the top-level BSON document from
embedded documents, respectively.
A type map may specify any class that implements
MongoDB\BSON\Unserializable as well as
"array"
, "stdClass
”, and "object"
("stdClass
” and "object"
are aliases of one another).
See also
Deserialization from BSON in the PHP manual
Persistable
Classes
The driver’s persistence specification outlines how classes implementing its MongoDB\BSON\Persistable interface are serialized to and deserialized from BSON. The Persistable interface is analogous to PHP’s Serializable interface.
The driver automatically handles serialization and deserialization for classes
implementing the Persistable interface without
requiring the use of the typeMap
option. This is done by encoding the name
of the PHP class in a special property within the BSON document.
Note
When deserializing a PHP variable from BSON, the encoded class name of a
Persistable object will override any class
specified in the type map, but it will not override "array"
and
"stdClass"
or "object"
. This is discussed in the
persistence specification but it bears
repeating.
Consider the following class definition:
The following example constructs a Person
object, inserts it into the
database, and reads it back as an object of the same type:
The output would then resemble:
The same document in the MongoDB shell might display as:
Note
MongoDB\BSON\Persistable may only be used for root and embedded BSON documents. It may not be used for BSON arrays.
Emulating the Legacy Driver
The legacy mongo extension returned both BSON documents and arrays as PHP arrays. While PHP arrays are convenient to work with, this behavior was problematic:
- Different BSON types could deserialize to the same PHP value (e.g.
{"0": "foo"}
and["foo"]
), which made it impossible to infer the original BSON type. - Numerically-indexed PHP arrays would be serialized as BSON documents if there was a gap in their key sequence. Such gaps were easily caused by unsetting a key to remove an element and forgetting to numerically reindex the array.
The MongoDB PHP Library’s BSONDocument
and
BSONArray
classes address these concerns
by preserving the BSON type information during serialization and
deserialization; however, some users may still prefer the legacy behavior. If
desired, you can use the typeMap
option to have the library return
everything as a PHP array:
The above example would output something similar to: