<!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>Serialization to BSON</title> </head> <body><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="mongodb.persistence.html">Persisting Data</a></div> <div class="next" style="text-align: right; float: right;"><a href="mongodb.persistence.deserialization.html">Deserialization from BSON</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.serialization" class="section"> <h2 class="title">Serialization to BSON</h2> <div class="section"> <h2 class="title">Arrays</h2> <p class="para"> If an array is a <em class="emphasis">packed array</em> — i.e. the keys start at 0 and are sequential without gaps: <em class="emphasis">BSON array</em>. </p> <p class="para"> If the array is not packed — i.e. having associative (string) keys, the keys don't start at 0, or when there are gaps:: <em class="emphasis">BSON object</em> </p> <p class="para"> A top-level (root) document, <em class="emphasis">always</em> serializes as a BSON document. </p> <div class="section"> <h2 class="title">Examples</h2> <p class="para"> These serialize as a BSON array: </p> <div class="example-contents"> <div class="textcode"><pre class="textcode">[ 8, 5, 2, 3 ] => [ 8, 5, 2, 3 ] [ 0 => 4, 1 => 9 ] => [ 4, 9 ]</pre> </div> </div> <p class="para"> These serialize as a BSON document: </p> <div class="example-contents"> <div class="textcode"><pre class="textcode">[ 0 => 1, 2 => 8, 3 => 12 ] => { "0" : 1, "2" : 8, "3" : 12 } [ "foo" => 42 ] => { "foo" : 42 } [ 1 => 9, 0 => 10 ] => { "1" : 9, "0" : 10 }</pre> </div> </div> <p class="para"> Note that the five examples are <em class="emphasis">extracts</em> of a full document, and represent only <em class="emphasis">one</em> value inside a document. </p> </div> </div> <div class="section"> <h2 class="title">Objects</h2> <p class="para"> If an object is of the <strong class="classname">stdClass</strong> class, serialize as a <em class="emphasis">BSON document</em>. </p> <p class="para"> If an object is a supported class that implements <span class="interfacename"><a href="class.mongodb-bson-type.html" class="interfacename">MongoDB\BSON\Type</a></span>, then use the BSON serialization logic for that specific type. <span class="interfacename"><a href="class.mongodb-bson-type.html" class="interfacename">MongoDB\BSON\Type</a></span> instances (excluding <span class="interfacename"><a href="class.mongodb-bson-serializable.html" class="interfacename">MongoDB\BSON\Serializable</a></span> may only be serialized as a document field value. Attempting to serialize such an object as a root document will throw a <a href="class.mongodb-driver-exception-unexpectedvalueexception.html" class="classname">MongoDB\Driver\Exception\UnexpectedValueException</a> </p> <p class="para"> If an object is of an unknown class implementing the <span class="interfacename"><a href="class.mongodb-bson-type.html" class="interfacename">MongoDB\BSON\Type</a></span> interface, then throw a <a href="class.mongodb-driver-exception-unexpectedvalueexception.html" class="classname">MongoDB\Driver\Exception\UnexpectedValueException</a> </p> <p class="para"> If an object is of any other class, without implementing any special interface, serialize as a <em class="emphasis">BSON document</em>. Keep only <em class="emphasis">public</em> properties, and ignore <em class="emphasis">protected</em> and <em class="emphasis">private</em> properties. </p> <p class="para"> If an object is of a class that implements the <span class="interfacename"><a href="class.mongodb-bson-serializable.html" class="interfacename">MongoDB\BSON\Serializable</a></span> interface, call <span class="methodname"><a href="mongodb-bson-serializable.bsonserialize.html" class="methodname">MongoDB\BSON\Serializable::bsonSerialize()</a></span> and use the returned array or <strong class="classname">stdClass</strong> to serialize as a BSON document or array. The BSON type will be determined by the following: </p> <p class="para"> <ol type="1"> <li class="listitem"> <p class="para">Root documents must be serialized as a BSON document. </p> </li> <li class="listitem"> <p class="para"> <span class="interfacename"><a href="class.mongodb-bson-persistable.html" class="interfacename">MongoDB\BSON\Persistable</a></span> objects must be serialized as a BSON document. </p> </li> <li class="listitem"> <p class="para"> If <span class="methodname"><a href="mongodb-bson-serializable.bsonserialize.html" class="methodname">MongoDB\BSON\Serializable::bsonSerialize()</a></span> returns a packed array, serialize as a BSON array. </p> </li> <li class="listitem"> <p class="para"> If <span class="methodname"><a href="mongodb-bson-serializable.bsonserialize.html" class="methodname">MongoDB\BSON\Serializable::bsonSerialize()</a></span> returns a non-packed array or <strong class="classname">stdClass</strong>, serialize as a BSON document. </p> </li> <li class="listitem"> <p class="para"> If <span class="methodname"><a href="mongodb-bson-serializable.bsonserialize.html" class="methodname">MongoDB\BSON\Serializable::bsonSerialize()</a></span> did not return an array or <strong class="classname">stdClass</strong>, throw an <a href="class.mongodb-driver-exception-unexpectedvalueexception.html" class="classname">MongoDB\Driver\Exception\UnexpectedValueException</a> exception. </p> </li> </ol> </p> <p class="para"> If an object is of a class that implements the <span class="interfacename"><a href="class.mongodb-bson-persistable.html" class="interfacename">MongoDB\BSON\Persistable</a></span> interface (which implies <span class="interfacename"><a href="class.mongodb-bson-serializable.html" class="interfacename">MongoDB\BSON\Serializable</a></span>), obtain the properties in a similar way as in the previous paragraphs, but <em class="emphasis">also</em> add an additional property <span class="property">__pclass</span> as a Binary value, with subtype <em>0x80</em> and data bearing the fully qualified class name of the object that is being serialized. </p> <p class="para"> The <span class="property">__pclass</span> property is added to the array or object returned by <span class="methodname"><a href="mongodb-bson-serializable.bsonserialize.html" class="methodname">MongoDB\BSON\Serializable::bsonSerialize()</a></span>, which means it will overwrite any <span class="property">__pclass</span> key/property in the <span class="methodname"><a href="mongodb-bson-serializable.bsonserialize.html" class="methodname">MongoDB\BSON\Serializable::bsonSerialize()</a></span> return value. If you want to avoid this behaviour and set your own <span class="property">__pclass</span> value, you must <em class="emphasis">not</em> implement <span class="interfacename"><a href="class.mongodb-bson-persistable.html" class="interfacename">MongoDB\BSON\Persistable</a></span> and should instead implement <span class="interfacename"><a href="class.mongodb-bson-serializable.html" class="interfacename">MongoDB\BSON\Serializable</a></span> directly. </p> <div class="section"> <h2 class="title">Examples</h2> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"> <span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">class </span><span style="color: #0000BB">stdClass </span><span style="color: #007700">{<br /> public </span><span style="color: #0000BB">$foo </span><span style="color: #007700">= </span><span style="color: #0000BB">42</span><span style="color: #007700">;<br />} </span><span style="color: #FF8000">// => { "foo" : 42 }<br /><br /></span><span style="color: #007700">class </span><span style="color: #0000BB">MyClass </span><span style="color: #007700">{<br /> public </span><span style="color: #0000BB">$foo </span><span style="color: #007700">= </span><span style="color: #0000BB">42</span><span style="color: #007700">;<br /> protected </span><span style="color: #0000BB">$prot </span><span style="color: #007700">= </span><span style="color: #DD0000">"wine"</span><span style="color: #007700">;<br /> private </span><span style="color: #0000BB">$fpr </span><span style="color: #007700">= </span><span style="color: #DD0000">"cheese"</span><span style="color: #007700">;<br />} </span><span style="color: #FF8000">// => { "foo" : 42 }<br /><br /></span><span style="color: #007700">class </span><span style="color: #0000BB">AnotherClass1 </span><span style="color: #007700">implements </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">BSON</span><span style="color: #007700">\</span><span style="color: #0000BB">Serializable </span><span style="color: #007700">{<br /> public </span><span style="color: #0000BB">$foo </span><span style="color: #007700">= </span><span style="color: #0000BB">42</span><span style="color: #007700">;<br /> protected </span><span style="color: #0000BB">$prot </span><span style="color: #007700">= </span><span style="color: #DD0000">"wine"</span><span style="color: #007700">;<br /> private </span><span style="color: #0000BB">$fpr </span><span style="color: #007700">= </span><span style="color: #DD0000">"cheese"</span><span style="color: #007700">;<br /> function </span><span style="color: #0000BB">bsonSerialize</span><span style="color: #007700">() {<br /> return [ </span><span style="color: #DD0000">'foo' </span><span style="color: #007700">=> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">foo</span><span style="color: #007700">, </span><span style="color: #DD0000">'prot' </span><span style="color: #007700">=> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">prot </span><span style="color: #007700">];<br /> }<br />} </span><span style="color: #FF8000">// => { "foo" : 42, "prot" : "wine" }<br /><br /></span><span style="color: #007700">class </span><span style="color: #0000BB">AnotherClass2 </span><span style="color: #007700">implements </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">BSON</span><span style="color: #007700">\</span><span style="color: #0000BB">Serializable </span><span style="color: #007700">{<br /> public </span><span style="color: #0000BB">$foo </span><span style="color: #007700">= </span><span style="color: #0000BB">42</span><span style="color: #007700">;<br /> function </span><span style="color: #0000BB">bsonSerialize</span><span style="color: #007700">() {<br /> return </span><span style="color: #0000BB">$this</span><span style="color: #007700">;<br /> }<br />} </span><span style="color: #FF8000">// => MongoDB\Driver\Exception\UnexpectedValueException("bsonSerialize() did not return an array or stdClass")<br /><br /></span><span style="color: #007700">class </span><span style="color: #0000BB">AnotherClass3 </span><span style="color: #007700">implements </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">BSON</span><span style="color: #007700">\</span><span style="color: #0000BB">Serializable </span><span style="color: #007700">{<br /> private </span><span style="color: #0000BB">$elements </span><span style="color: #007700">= [ </span><span style="color: #DD0000">'foo'</span><span style="color: #007700">, </span><span style="color: #DD0000">'bar' </span><span style="color: #007700">];<br /> function </span><span style="color: #0000BB">bsonSerialize</span><span style="color: #007700">() {<br /> return </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">elements</span><span style="color: #007700">;<br /> }<br />} </span><span style="color: #FF8000">// => { "0" : "foo", "1" : "bar" }<br /><br /></span><span style="color: #007700">class </span><span style="color: #0000BB">ContainerClass </span><span style="color: #007700">implements </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">BSON</span><span style="color: #007700">\</span><span style="color: #0000BB">Serializable </span><span style="color: #007700">{<br /> public </span><span style="color: #0000BB">$things </span><span style="color: #007700">= </span><span style="color: #0000BB">AnotherClass4 </span><span style="color: #007700">implements </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">BSON</span><span style="color: #007700">\</span><span style="color: #0000BB">Serializable </span><span style="color: #007700">{<br /> private </span><span style="color: #0000BB">$elements </span><span style="color: #007700">= [ </span><span style="color: #0000BB">0 </span><span style="color: #007700">=> </span><span style="color: #DD0000">'foo'</span><span style="color: #007700">, </span><span style="color: #0000BB">2 </span><span style="color: #007700">=> </span><span style="color: #DD0000">'bar' </span><span style="color: #007700">];<br /> function </span><span style="color: #0000BB">bsonSerialize</span><span style="color: #007700">() {<br /> return </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">elements</span><span style="color: #007700">;<br /> }<br /> }<br /> function </span><span style="color: #0000BB">bsonSerialize</span><span style="color: #007700">() {<br /> return [ </span><span style="color: #DD0000">'things' </span><span style="color: #007700">=> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">things </span><span style="color: #007700">];<br /> }<br />} </span><span style="color: #FF8000">// => { "things" : { "0" : "foo", "2" : "bar" } }<br /><br /></span><span style="color: #007700">class </span><span style="color: #0000BB">ContainerClass </span><span style="color: #007700">implements </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">BSON</span><span style="color: #007700">\</span><span style="color: #0000BB">Serializable </span><span style="color: #007700">{<br /> public </span><span style="color: #0000BB">$things </span><span style="color: #007700">= </span><span style="color: #0000BB">AnotherClass5 </span><span style="color: #007700">implements </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">BSON</span><span style="color: #007700">\</span><span style="color: #0000BB">Serializable </span><span style="color: #007700">{<br /> private </span><span style="color: #0000BB">$elements </span><span style="color: #007700">= [ </span><span style="color: #0000BB">0 </span><span style="color: #007700">=> </span><span style="color: #DD0000">'foo'</span><span style="color: #007700">, </span><span style="color: #0000BB">2 </span><span style="color: #007700">=> </span><span style="color: #DD0000">'bar' </span><span style="color: #007700">];<br /> function </span><span style="color: #0000BB">bsonSerialize</span><span style="color: #007700">() {<br /> return </span><span style="color: #0000BB">array_values</span><span style="color: #007700">(</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">elements</span><span style="color: #007700">);<br /> }<br /> }<br /> function </span><span style="color: #0000BB">bsonSerialize</span><span style="color: #007700">() {<br /> return [ </span><span style="color: #DD0000">'things' </span><span style="color: #007700">=> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">things </span><span style="color: #007700">];<br /> }<br />} </span><span style="color: #FF8000">// => { "things" : [ "foo", "bar" ] }<br /><br /></span><span style="color: #007700">class </span><span style="color: #0000BB">ContainerClass </span><span style="color: #007700">implements </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">BSON</span><span style="color: #007700">\</span><span style="color: #0000BB">Serializable </span><span style="color: #007700">{<br /> public </span><span style="color: #0000BB">$things </span><span style="color: #007700">= </span><span style="color: #0000BB">AnotherClass6 </span><span style="color: #007700">implements </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">BSON</span><span style="color: #007700">\</span><span style="color: #0000BB">Serializable </span><span style="color: #007700">{<br /> private </span><span style="color: #0000BB">$elements </span><span style="color: #007700">= [ </span><span style="color: #DD0000">'foo'</span><span style="color: #007700">, </span><span style="color: #DD0000">'bar' </span><span style="color: #007700">];<br /> function </span><span style="color: #0000BB">bsonSerialize</span><span style="color: #007700">() {<br /> return (object) </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">elements</span><span style="color: #007700">;<br /> }<br /> }<br /> function </span><span style="color: #0000BB">bsonSerialize</span><span style="color: #007700">() {<br /> return [ </span><span style="color: #DD0000">'things' </span><span style="color: #007700">=> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">things </span><span style="color: #007700">];<br /> }<br />} </span><span style="color: #FF8000">// => { "things" : { "0" : "foo", "1" : "bar" } }<br /><br /></span><span style="color: #007700">class </span><span style="color: #0000BB">UpperClass </span><span style="color: #007700">implements </span><span style="color: #0000BB">MongoDB</span><span style="color: #007700">\</span><span style="color: #0000BB">BSON</span><span style="color: #007700">\</span><span style="color: #0000BB">Persistable </span><span style="color: #007700">{<br /> public </span><span style="color: #0000BB">$foo </span><span style="color: #007700">= </span><span style="color: #0000BB">42</span><span style="color: #007700">;<br /> protected </span><span style="color: #0000BB">$prot </span><span style="color: #007700">= </span><span style="color: #DD0000">"wine"</span><span style="color: #007700">;<br /> private </span><span style="color: #0000BB">$fpr </span><span style="color: #007700">= </span><span style="color: #DD0000">"cheese"</span><span style="color: #007700">;<br /> function </span><span style="color: #0000BB">bsonSerialize</span><span style="color: #007700">() {<br /> return [ </span><span style="color: #DD0000">'foo' </span><span style="color: #007700">=> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">foo</span><span style="color: #007700">, </span><span style="color: #DD0000">'prot' </span><span style="color: #007700">=> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">prot </span><span style="color: #007700">];<br /> }<br />} </span><span style="color: #FF8000">// => { "foo" : 42, "prot" : "wine", "__pclass" : { "$type" : "80", "$binary" : "VXBwZXJDbGFzcw==" } }</span> </span> </code></div> </div> </div> </div> </div><hr /><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="mongodb.persistence.html">Persisting Data</a></div> <div class="next" style="text-align: right; float: right;"><a href="mongodb.persistence.deserialization.html">Deserialization from BSON</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>