From 03760a2565082393f93ac0f50c1525970e100e1b Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@php.net>
Date: Thu, 29 Oct 2015 22:38:16 +0000
Subject: [PATCH] Update MongoDB\BSON serializable interfaces

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@338057 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongodb/bson/serializable.xml       |   3 +-
 .../bson/serializable/bsonserialize.xml       | 133 +++++++++++++++---
 reference/mongodb/bson/unserializable.xml     |   4 +-
 .../bson/unserializable/bsonunserialize.xml   |  57 +++++---
 4 files changed, 160 insertions(+), 37 deletions(-)

diff --git a/reference/mongodb/bson/serializable.xml b/reference/mongodb/bson/serializable.xml
index bd78cf93e6..2f923b0b66 100644
--- a/reference/mongodb/bson/serializable.xml
+++ b/reference/mongodb/bson/serializable.xml
@@ -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&apos;s public properties.
    </para>
   </section>
 <!-- }}} -->
diff --git a/reference/mongodb/bson/serializable/bsonserialize.xml b/reference/mongodb/bson/serializable/bsonserialize.xml
index 6f6b6ede29..ec00004906 100644
--- a/reference/mongodb/bson/serializable/bsonserialize.xml
+++ b/reference/mongodb/bson/serializable/bsonserialize.xml
@@ -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>
 
diff --git a/reference/mongodb/bson/unserializable.xml b/reference/mongodb/bson/unserializable.xml
index 8b3c2746f5..565d003d84 100644
--- a/reference/mongodb/bson/unserializable.xml
+++ b/reference/mongodb/bson/unserializable.xml
@@ -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>
 <!-- }}} -->
diff --git a/reference/mongodb/bson/unserializable/bsonunserialize.xml b/reference/mongodb/bson/unserializable/bsonunserialize.xml
index 49a508cb0c..1e6feb4d37 100644
--- a/reference/mongodb/bson/unserializable/bsonunserialize.xml
+++ b/reference/mongodb/bson/unserializable/bsonunserialize.xml
@@ -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>