mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
Update MongoDB\BSON serializable interfaces
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@338057 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Jeremy Mikola
parent
aec2c04902
commit
03760a2565
4 changed files with 160 additions and 37 deletions
|
|
@ -12,7 +12,8 @@
|
|||
<section xml:id="mongodb-bson-serializable.intro">
|
||||
&reftitle.intro;
|
||||
<para>
|
||||
|
||||
Classes that implement this interface may return data to be serialized as a
|
||||
BSON array or document in lieu of the object's public properties.
|
||||
</para>
|
||||
</section>
|
||||
<!-- }}} -->
|
||||
|
|
|
|||
|
|
@ -4,19 +4,27 @@
|
|||
<refentry xml:id="mongodb-bson-serializable.bsonserialize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<refnamediv>
|
||||
<refname>MongoDB\BSON\Serializable::bsonSerialize</refname>
|
||||
<refpurpose>Description</refpurpose>
|
||||
<refpurpose>Provides an array or document to serialize as BSON</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<modifier>abstract</modifier> <modifier>public</modifier> <type>ReturnType</type><methodname>MongoDB\BSON\Serializable::bsonSerialize</methodname>
|
||||
<modifier>abstract</modifier> <modifier>public</modifier> <type>array|object</type><methodname>MongoDB\BSON\Serializable::bsonSerialize</methodname>
|
||||
<void />
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
|
||||
Called during serialization of the object to BSON. The method must return an
|
||||
<type>array</type> or <classname>stdClass</classname>.
|
||||
</para>
|
||||
<para>
|
||||
Root documents (e.g. a <classname>MongoDB\BSON\Serializable</classname>
|
||||
passed to <function>MongoDB\BSON\fromPHP</function>) will always be
|
||||
serialized as a BSON document. For field values, associative arrays and
|
||||
<classname>stdClass</classname> instances will be serialized as a BSON
|
||||
document and sequential arrays (i.e. sequential, numeric indexes starting at
|
||||
<literal>0</literal>) will be serialized as a BSON array.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="parameters">
|
||||
|
|
@ -27,14 +35,8 @@
|
|||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="errors">
|
||||
&reftitle.errors;
|
||||
<para>
|
||||
|
||||
An <type>array</type> or <classname>stdClass</classname> to be serialized as
|
||||
a BSON array or document.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
|
@ -42,20 +44,115 @@
|
|||
<refsect1 role="examples">
|
||||
&reftitle.examples;
|
||||
<example>
|
||||
<title><function>MongoDB\BSON\Serializable::bsonSerialize</function> example</title>
|
||||
<title><function>MongoDB\BSON\Serializable::bsonSerialize</function> returning an associative array for root document</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
|
||||
/* ... */
|
||||
class MyDocument implements MongoDB\BSON\Serializable
|
||||
{
|
||||
function bsonSerialize()
|
||||
{
|
||||
return ['foo' => 'bar'];
|
||||
}
|
||||
}
|
||||
|
||||
$bson = MongoDB\BSON\fromPHP(new MyDocument);
|
||||
echo MongoDB\BSON\toJSON($bson), "\n";
|
||||
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs.similar;
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
...
|
||||
{ "foo" : "bar" }
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title><function>MongoDB\BSON\Serializable::bsonSerialize</function> returning a sequential array for root document</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
|
||||
class MyArray implements MongoDB\BSON\Serializable
|
||||
{
|
||||
function bsonSerialize()
|
||||
{
|
||||
return [1, 2, 3];
|
||||
}
|
||||
}
|
||||
|
||||
$bson = MongoDB\BSON\fromPHP(new MyArray);
|
||||
echo MongoDB\BSON\toJSON($bson), "\n";
|
||||
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
{ "0" : 1, "1" : 2, "2" : 3 }
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title><function>MongoDB\BSON\Serializable::bsonSerialize</function> returning an associative array for document field</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
|
||||
class MyDocument implements MongoDB\BSON\Serializable
|
||||
{
|
||||
function bsonSerialize()
|
||||
{
|
||||
return ['foo' => 'bar'];
|
||||
}
|
||||
}
|
||||
|
||||
$value = ['document' => new MyDocument];
|
||||
$bson = MongoDB\BSON\fromPHP($value);
|
||||
echo MongoDB\BSON\toJSON($bson), "\n";
|
||||
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
{ "document" : { "foo" : "bar" } }
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title><function>MongoDB\BSON\Serializable::bsonSerialize</function> returning a sequential array for document field</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
|
||||
class MyArray implements MongoDB\BSON\Serializable
|
||||
{
|
||||
function bsonSerialize()
|
||||
{
|
||||
return [1, 2, 3];
|
||||
}
|
||||
}
|
||||
|
||||
$value = ['array' => new MyArray];
|
||||
$bson = MongoDB\BSON\fromPHP($value);
|
||||
echo MongoDB\BSON\toJSON($bson), "\n";
|
||||
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
{ "array" : [ 1, 2, 3 ] }
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
|
|
@ -65,7 +162,9 @@
|
|||
<refsect1 role="seealso">
|
||||
&reftitle.seealso;
|
||||
<simplelist>
|
||||
<member></member>
|
||||
<member><function>MongoDB\BSON\Unzerializable::bsonUnserialize</function></member>
|
||||
<member><classname>MongoDB\BSON\Persistable</classname></member>
|
||||
<member><xref linkend="mongodb.persistence"/></member>
|
||||
</simplelist>
|
||||
</refsect1>
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,9 @@
|
|||
<section xml:id="mongodb-bson-unserializable.intro">
|
||||
&reftitle.intro;
|
||||
<para>
|
||||
|
||||
Classes that implement this interface may be specified in a
|
||||
<link linkend="mongodb.persistence.typemaps">type map</link> for
|
||||
unserializing BSON arrays and documents (both root and embedded).
|
||||
</para>
|
||||
</section>
|
||||
<!-- }}} -->
|
||||
|
|
|
|||
|
|
@ -4,29 +4,37 @@
|
|||
<refentry xml:id="mongodb-bson-unserializable.bsonunserialize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<refnamediv>
|
||||
<refname>MongoDB\BSON\Unserializable::bsonUnserialize</refname>
|
||||
<refpurpose>Description</refpurpose>
|
||||
<refpurpose>Constructs the object from a BSON array or document</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<modifier>abstract</modifier> <modifier>public</modifier> <type>ReturnType</type><methodname>MongoDB\BSON\Unserializable::bsonUnserialize</methodname>
|
||||
<modifier>abstract</modifier> <modifier>public</modifier> <type>void</type><methodname>MongoDB\BSON\Unserializable::bsonUnserialize</methodname>
|
||||
<methodparam><type>array</type><parameter>data</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
|
||||
Called during unserialization of the object from BSON. The properties of the
|
||||
BSON array or document will be passed to the method as an <type>array</type>.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
This method acts as the
|
||||
<link linkend="language.oop5.decon.constructor">constructor</link> of the
|
||||
object. The <link linkend="object.construct">__construct()</link> method
|
||||
will <emphasis>not</emphasis> be called after this method.
|
||||
</para>
|
||||
</note>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><parameter>data</parameter></term>
|
||||
<term><parameter>data</parameter> (<type>array</type>)</term>
|
||||
<listitem>
|
||||
<para>
|
||||
|
||||
Properties within the BSON array or document.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -36,14 +44,7 @@
|
|||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="errors">
|
||||
&reftitle.errors;
|
||||
<para>
|
||||
|
||||
The return value from this method is ignored.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
|
@ -56,15 +57,33 @@
|
|||
<![CDATA[
|
||||
<?php
|
||||
|
||||
/* ... */
|
||||
class MyDocument implements MongoDB\BSON\Unserializable
|
||||
{
|
||||
private $data = [];
|
||||
|
||||
function bsonUnserialize(array $data)
|
||||
{
|
||||
$this->data = $data;
|
||||
}
|
||||
}
|
||||
|
||||
$bson = MongoDB\BSON\fromJSON('{ "foo": "bar" }');
|
||||
$value = MongoDB\BSON\toPHP($bson, ['root' => 'MyDocument']);
|
||||
var_dump($value);
|
||||
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs.similar;
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
...
|
||||
object(MyDocument)#1 (1) {
|
||||
["data":"MyDocument":private]=>
|
||||
array(1) {
|
||||
["foo"]=>
|
||||
string(3) "bar"
|
||||
}
|
||||
}
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
|
|
@ -74,7 +93,9 @@
|
|||
<refsect1 role="seealso">
|
||||
&reftitle.seealso;
|
||||
<simplelist>
|
||||
<member></member>
|
||||
<member><function>MongoDB\BSON\Serializable::bsonSerialize</function></member>
|
||||
<member><classname>MongoDB\BSON\Persistable</classname></member>
|
||||
<member><xref linkend="mongodb.persistence"/></member>
|
||||
</simplelist>
|
||||
</refsect1>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue