<!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>Deserialization from BSON</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongodb.persistence.serialization.html">Serialization to BSON</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongodb.security.html">Security</a></div>
<div class="up"><a href="mongodb.persistence.html">Persisting Data</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongodb.persistence.deserialization" class="section">
<h2 class="title">Deserialization from BSON</h2>
<p class="para">
The legacy <a href="book.mongo.html" class="link">mongo</a> extension deserialized
both BSON documents and arrays as PHP arrays. While PHP arrays are
convenient to work with, this behavior was problematic because different
BSON types could deserialize to the same PHP value (e.g.
<em>{"0": "foo"}</em> and <em>["foo"]</em>) and make it
impossible to infer the original BSON type. By default, the current driver
addresses this concern by ensuring that BSON arrays and documents are
converted to PHP arrays and objects, respectively.
</p>
<p class="para">
For compound types, there are three data types:
</p>
<p class="para">
<dl>
<dt>
root</dt>
<dd>
<p class="para">
refers to the top-level BSON document <em class="emphasis">only</em>
</p>
</dd>
<dt>
document</dt>
<dd>
<p class="para">
refers to embedded BSON documents <em class="emphasis">only</em>
</p>
</dd>
<dt>
array</dt>
<dd>
<p class="para">
refers to a BSON array
</p>
</dd>
</dl>
</p>
<p class="para">
Besides the three collective types, it is also possible to configure
specific fields in your document to map to the data types mentioned below.
As an example, the following type map allows you to
map each embedded document within an <em>"addresses"</em> array to
an <strong class="classname">Address</strong> class <em class="emphasis">and</em> each
<em>"city"</em> field within those embedded address documents to
a <strong class="classname">City</strong> class:
<div class="example-contents">
<div class="textcode"><pre class="textcode">[
'fieldPaths' => [
'addresses.$' => 'MyProject\Address',
'addresses.$.city' => 'MyProject\City',
],
]</pre>
</div>
</div>
</p>
<p class="para">
Each of those three data types, as well as the field specific mappings,
can be mapped against different PHP types. The possible mapping values
are:
</p>
<p class="para">
<dl>
<dt>
<em class="emphasis">not set</em> or <span class="type"><a href="language.types.null.html" class="type NULL">NULL</a></span> (default)</dt>
<dd>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
A BSON array will be deserialized as a PHP <span class="type"><a href="language.types.array.html" class="type array">array</a></span>.
</p>
</li>
<li class="listitem">
<p class="para">
A BSON document (root or embedded) without a
<span class="property">__pclass</span> property
<a href="#fnidmongodb.pclass" name="fnmongodb.pclass"><sup>[1]</sup></a>
becomes a PHP <strong class="classname">stdClass</strong> object, with each
BSON document key set as a public <strong class="classname">stdClass</strong>
property.
</p>
</li>
<li class="listitem">
<p class="para">
A BSON document (root or embedded) with a
<span class="property">__pclass</span> property <a href="#fnidmongodb.pclass"><sup>[1]</sup></a> becomes a PHP object of
the class name as defined by the <span class="property">__pclass</span>
property.
</p>
<p class="para">
If the named class implements the
<span class="interfacename"><a href="class.mongodb-bson-persistable.html" class="interfacename">MongoDB\BSON\Persistable</a></span> interface,
then the properties of the BSON document, including the
<span class="property">__pclass</span> property, are sent as an associative
array to the
<span class="methodname"><a href="mongodb-bson-unserializable.bsonunserialize.html" class="methodname">MongoDB\BSON\Unserializable::bsonUnserialize()</a></span>
function to initialise the object's properties.
</p>
<p class="para">
If the named class does not exist or does not implement the
<span class="interfacename"><a href="class.mongodb-bson-persistable.html" class="interfacename">MongoDB\BSON\Persistable</a></span> interface,
<strong class="classname">stdClass</strong> will be used and each BSON document
key (including <span class="property">__pclass</span>) will be set as a
public <strong class="classname">stdClass</strong> property.
</p>
<p class="para">
The <span class="property">__pclass</span> functionality relies on the
property being part of a retrieved MongoDB document. If you use a
<a href="mongodb-driver-query.construct.html#mongodb-driver-query.construct-queryOptions" class="link">projection</a>
when querying for documents, you need to include the
<span class="property">__pclass</span> field in the projection for this
functionality to work.
</p>
</li>
</ul>
</p>
</dd>
<dt>
<em>"array"</em></dt>
<dd>
<p class="para">
Turns a BSON array or BSON document into a PHP array. There will be no
special treatment of a <span class="property">__pclass</span> property <a href="#fnidmongodb.pclass"><sup>[1]</sup></a>,
but it may be set as an element in the returned array if it was
present in the BSON document.
</p>
</dd>
<dt>
<em>"object"</em> or <em>"stdClass"</em></dt>
<dd>
<p class="para">
Turns a BSON array or BSON document into a
<strong class="classname">stdClass</strong> object. There will be no special
treatment of a <span class="property">__pclass</span> property <a href="#fnidmongodb.pclass"><sup>[1]</sup></a>, but it may
be set as a public property in the returned object if it was present
in the BSON document.
</p>
</dd>
<dt>
any other string</dt>
<dd>
<p class="para">
Defines the class name that the BSON array or BSON object should be
deserialized as. For BSON objects that include
<span class="property">__pclass</span> properties, that class will take
priority.
</p>
<p class="para">
If the named class does not exist, is not concrete (i.e. it is
abstract or an interface), or does not implement
<span class="interfacename"><a href="class.mongodb-bson-unserializable.html" class="interfacename">MongoDB\BSON\Unserializable</a></span> then an
<a href="class.mongodb-driver-exception-invalidargumentexception.html" class="classname">MongoDB\Driver\Exception\InvalidArgumentException</a>
exception is thrown.
</p>
<p class="para">
If the BSON object has a <span class="property">__pclass</span> property and
that class exists and implements
<span class="interfacename"><a href="class.mongodb-bson-persistable.html" class="interfacename">MongoDB\BSON\Persistable</a></span> it will
supersede the class provided in the type map.
</p>
<p class="para">
The properties of the BSON document, <em class="emphasis">including</em>
the <span class="property">__pclass</span> property if it exists, will be sent
as an associative array to the
<span class="methodname"><a href="mongodb-bson-unserializable.bsonunserialize.html" class="methodname">MongoDB\BSON\Unserializable::bsonUnserialize()</a></span>
function to initialise the object's properties.
</p>
</dd>
</dl>
</p>
<div class="section" id="mongodb.persistence.typemaps">
<h2 class="title">TypeMaps</h2>
<p class="para">
TypeMaps can be set through the
<span class="methodname"><a href="mongodb-driver-cursor.settypemap.html" class="methodname">MongoDB\Driver\Cursor::setTypeMap()</a></span> method on a
<a href="class.mongodb-driver-cursor.html" class="classname">MongoDB\Driver\Cursor</a> object, or the
<em>$typeMap</em> argument of
<span class="function"><a href="function.mongodb.bson-tophp.html" class="function">MongoDB\BSON\toPHP()</a></span>. Each of the three
classes (<em class="emphasis">root</em>, <em class="emphasis">document</em>, and
<em class="emphasis">array</em>) can be individually set, in addition to the
field specific types.
</p>
<p class="para">
If the value in the map is <span class="type"><a href="language.types.null.html" class="type NULL">NULL</a></span>, it means the same as the
<em class="emphasis">default</em> value for that item.
</p>
</div>
<div class="section">
<h2 class="title">Examples</h2>
<p class="para">
These examples use the following classes:
</p>
<p class="para">
<dl>
<dt>
MyClass</dt>
<dd>
<p class="para">
which does <em class="emphasis">not</em> implement any interface
</p>
</dd>
<dt>
YourClass</dt>
<dd>
<p class="para">
which implements
<span class="interfacename"><a href="class.mongodb-bson-unserializable.html" class="interfacename">MongoDB\BSON\Unserializable</a></span>
</p>
</dd>
<dt>
OurClass</dt>
<dd>
<p class="para">
which implements
<span class="interfacename"><a href="class.mongodb-bson-persistable.html" class="interfacename">MongoDB\BSON\Persistable</a></span>
</p>
</dd>
<dt>
TheirClass</dt>
<dd>
<p class="para">
which extends OurClass
</p>
</dd>
</dl>
</p>
<p class="para">
The <span class="methodname"><a href="mongodb-bson-unserializable.bsonunserialize.html" class="methodname">MongoDB\BSON\Unserializable::bsonUnserialize()</a></span>
method of YourClass, OurClass, TheirClass iterate over the array and set
the properties without modifications. It <em class="emphasis">also</em> sets
the <em>$unserialized</em> property to <em>true</em>:
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">function </span><span style="color: #0000BB">bsonUnserialize</span><span style="color: #007700">( array </span><span style="color: #0000BB">$map </span><span style="color: #007700">)<br />{<br /> foreach ( </span><span style="color: #0000BB">$map </span><span style="color: #007700">as </span><span style="color: #0000BB">$k </span><span style="color: #007700">=> </span><span style="color: #0000BB">$value </span><span style="color: #007700">)<br /> {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">$k </span><span style="color: #007700">= </span><span style="color: #0000BB">$value</span><span style="color: #007700">;<br /> }<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">unserialized </span><span style="color: #007700">= </span><span style="color: #0000BB">true</span><span style="color: #007700">;<br />}</span>
</span>
</code></div>
</div>
</p>
<p class="para">
<div class="example-contents">
<div class="textcode"><pre class="textcode">/* typemap: [] (all defaults) */
{ "foo": "yes", "bar" : false }
-> stdClass { $foo => 'yes', $bar => false }
{ "foo": "no", "array" : [ 5, 6 ] }
-> stdClass { $foo => 'no', $array => [ 5, 6 ] }
{ "foo": "no", "obj" : { "embedded" : 3.14 } }
-> stdClass { $foo => 'no', $obj => stdClass { $embedded => 3.14 } }
{ "foo": "yes", "__pclass": "MyClass" }
-> stdClass { $foo => 'yes', $__pclass => 'MyClass' }
{ "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "MyClass" } }
-> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'MyClass') }
{ "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "YourClass") }
-> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass') }
{ "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "OurClass") }
-> OurClass { $foo => 'yes', $__pclass => Binary(0x80, 'OurClass'), $unserialized => true }
{ "foo": "yes", "__pclass": { "$type" : "44", "$binary" : "YourClass") }
-> stdClass { $foo => 'yes', $__pclass => Binary(0x44, 'YourClass') }</pre>
</div>
</div>
</p>
<p class="para">
<div class="example-contents">
<div class="textcode"><pre class="textcode">/* typemap: [ "root" => "MissingClass" ] */
{ "foo": "yes" }
-> MongoDB\Driver\Exception\InvalidArgumentException("MissingClass does not exist")
/* typemap: [ "root" => "MyClass" ] */
{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
-> MongoDB\Driver\Exception\InvalidArgumentException("MyClass does not implement Unserializable interface")
/* typemap: [ "root" => "MongoDB\BSON\Unserializable" ] */
{ "foo": "yes" }
-> MongoDB\Driver\Exception\InvalidArgumentException("Unserializable is not a concrete class")
/* typemap: [ "root" => "YourClass" ] */
{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MongoDB\BSON\Unserializable" } }
-> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MongoDB\BSON\Unserializable"), $unserialized => true }
/* typemap: [ "root" => "YourClass" ] */
{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
-> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MyClass"), $unserialized => true }
/* typemap: [ "root" => "YourClass" ] */
{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
-> OurClass { $foo => "yes", $__pclass => Binary(0x80, "OurClass"), $unserialized => true }
/* typemap: [ "root" => "YourClass" ] */
{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
-> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true }
/* typemap: [ "root" => "OurClass" ] */
{ foo: "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
-> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true }</pre>
</div>
</div>
</p>
<p class="para">
<div class="example-contents">
<div class="textcode"><pre class="textcode">/* typemap: [ 'root' => 'YourClass' ] */
{ foo: "yes", "__pclass" : { "$type": "80", "$binary": "YourClass" } }
-> YourClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass'), $unserialized => true }</pre>
</div>
</div>
</p>
<p class="para">
<div class="example-contents">
<div class="textcode"><pre class="textcode">/* typemap: [ 'root' => 'array', 'document' => 'array' ] */
{ "foo": "yes", "bar" : false }
-> [ "foo" => "yes", "bar" => false ]
{ "foo": "no", "array" : [ 5, 6 ] }
-> [ "foo" => "no", "array" => [ 5, 6 ] ]
{ "foo": "no", "obj" : { "embedded" : 3.14 } }
-> [ "foo" => "no", "obj" => [ "embedded => 3.14 ] ]
{ "foo": "yes", "__pclass": "MyClass" }
-> [ "foo" => "yes", "__pclass" => "MyClass" ]
{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
-> [ "foo" => "yes", "__pclass" => Binary(0x80, "MyClass") ]
{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
-> [ "foo" => "yes", "__pclass" => Binary(0x80, "OurClass") ]</pre>
</div>
</div>
</p>
<p class="para">
<div class="example-contents">
<div class="textcode"><pre class="textcode">/* typemap: [ 'root' => 'object', 'document' => 'object' ] */
{ "foo": "yes", "__pclass": { "$type": "80", "$binary": "MyClass" } }
-> stdClass { $foo => "yes", "__pclass" => Binary(0x80, "MyClass") }</pre>
</div>
</div>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongodb.persistence.serialization.html">Serialization to BSON</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongodb.security.html">Security</a></div>
<div class="up"><a href="mongodb.persistence.html">Persisting Data</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
