RR feedback

Author: norareidy

source/data-formats/modeling-bson-data.txt

@@ -15,17 +15,17 @@ Overview
 --------
 
 In this guide, you can learn how to create and interact with BSON documents
-by using the {+driver-short+}.
+by using the {+library-short+}.
 
 **BSON**, or Binary JSON, is the data format that MongoDB uses to organize
 and store data. This data format includes all JSON data structure types and
-supports additional types, including dates, different-sized integers, ``ObjectId``
-values, and binary data. The {+library-short+} provides the ``MongoDB\Model\BSONArray``
-and ``MongoDB\Model\BSONDocument`` types to store BSON data.
+also supports other types, including dates, different-sized integers, ``ObjectId``
+values, and binary data. The {+library-short+} provides the :phpclass:`MongoDB\Model\BSONArray`
+and :phpclass:`MongoDB\Model\BSONDocument` types to store BSON data.
 
 .. tip::
 
-   For a complete list of supported BSON types, see :manual:`BSON Types
+   To view a complete list of supported BSON types, see :manual:`BSON Types
    </reference/bson-types>` in the {+mdb-server+} manual.
 
 .. _php-bson-sample:
@@ -44,13 +44,13 @@ The code examples in this guide reference the following sample BSON document:
        },
        "coord" : [-73.982419, 41.579505]
        "cuisine" : "Pizza",
-       "name" : "Mongo's Pizza"
+       "name" : "Planet Pizza"
    }
 
 Create a BSON Document
 ----------------------
 
-You can create a BSON document by using the same notation you use to create an
+You can create a BSON document by using the same notation that you use to create an
 associative array in {+language+}. The {+library-short+} automatically converts
 these values into BSON documents when inserting them into a collection.
 
@@ -66,41 +66,48 @@ The following example creates a BSON document that represents the preceding
 Change a BSON Document
 ----------------------
 
-You can modify the contents of a BSON document by using the same notation you use to
+You can modify the contents of a BSON document by using the same notation that you use to
 modify an associative array in {+language+}. This example makes the following changes
 to the :ref:`sample BSON document <php-bson-sample>`:
 
 - Adds a new ``restaurant_id`` field that has a value of ``12345``
-- Sets the value of the ``name`` field to ``"Mongo's Pizza Place"``
+- Changes the ``name`` field value to ``"Galaxy Pizza"``
 
 .. literalinclude:: /includes/bson.php
     :language: php
     :dedent:
     :start-after: start-modify-doc
     :end-before: end-modify-doc
 
+.. note::
+
+   The preceding code changes only the in-memory values of the sample BSON
+   document. It does not run any database operations that change values stored
+   in MongoDB. To learn how to modify documents stored in MongoDB, see the
+   :ref:`php-write-update` guide.
+
 Customize BSON Serialization
 ----------------------------
 
 The following sections describe how to configure your application's 
 serialization of BSON data:
 
 - :ref:`php-type-map`: Use the ``typeMap`` option to specify the default conversion
-  between {+language+} types and BSON types
+  between {+language+} types and BSON types.
 
 - :ref:`php-persistable-classes`: Use the ``MongoDB\BSON\Persistable`` interface to
-  enable serialization
+  enable serialization.
 
 - :ref:`php-enums`: Use the ``bsonSerialize()`` and ``bsonUnserialize()`` methods to
-  specify serialization between backed enums and BSON values
+  specify serialization between backed enums and BSON values.
 
 .. _php-type-map:
 
 Type Maps
 ~~~~~~~~~
 
-You can set the ``typeMap`` option, which configures how BSON values are converted to
-{+language+} values, at the following levels:
+You can set the ``typeMap`` option, which configures serialization and
+deserialization between {+language+} and BSON values, at the following levels:
 
 - ``MongoDB\Client``, which sets the *default for all operations* unless overridden
 - ``MongoDB\Database``
@@ -120,14 +127,14 @@ The {+library-short+} uses the following type map by default:
        'root' => 'MongoDB\Model\BSONDocument',
    ]
 
-This type map performs the following conversions:
+This type map performs the following conversions in both directions:
 
 - Arrays to ``MongoDB\Model\BSONArray`` objects
 - Top-level and embedded BSON documents to ``MongoDB\Model\BSONDocument`` objects
 
-A type map can specify any class that implements
-:php:`MongoDB\BSON\Unserializable <mongodb-bson-unserializable>`. It can
-also specify the ``array``, ``stdClass``, and ``object`` types.
+A type map can specify any class that implements the
+:php:`MongoDB\BSON\Unserializable <mongodb-bson-unserializable>` interface.
+It can also specify conversions of the ``array``, ``stdClass``, and ``object`` types.
 
 Custom Type Map Example
 ```````````````````````
@@ -146,25 +153,22 @@ that serializes arrays and BSON documents as ``MongoDB\Model\BSONDocument`` obje
 Persistable Classes
 ~~~~~~~~~~~~~~~~~~~
 
-You can create classes that implement the ``MongoDB\BSON\Persistable`` interface,
-which instructs the {+library-short+} to automatically perform serialization and
-deserialization according to the {+extension-short+}'s :php:`persistence specification
-<mongodb.persistence>`. The ``Persistable`` interface is analogous to {+language+}'s
-:php:`Serializable interface <class.serializable>`.
+You can create classes that implement the :php:`MongoDB\BSON\Persistable <mongodb-bson-persistable>`
+interface. This interface instructs the {+library-short+} to automatically perform serialization
+and deserialization according to the {+extension-short+}'s :php:`persistence specification
+<mongodb.persistence>` without requiring the ``typeMap`` option. The ``Persistable`` interface
+is analogous to {+language+}'s :php:`Serializable interface <class.serializable>`.
 
 When deserializing a PHP variable from BSON, the encoded class name of a
 ``Persistable`` object overrides any class specified in the ``typeMap`` option.
 However, it does not override ``array``,  ``stdClass``, or ``object`` types.
 
-.. tip::
-
-   To learn more about the ``Persistable`` interface, see :php:`Persistable <mongodb-bson-persistable>`
-   in the {+extension-short+} documentation.
-
 Example
 ```````
 
-Consider the following ``Person`` class definition:
+Consider the following ``Person`` class definition, which implements the
+``Persistable`` interface and specifies how to serialize and deserialize
+object fields as BSON values:
 
 .. literalinclude:: /includes/bson.php
     :language: php
@@ -213,6 +217,10 @@ The returned document is equivalent to the following BSON document:
      "createdAt" : ISODate("2016-03-29T19:08:51.218Z")
    }
 
+The {+library-short+} automatically adds the ``__pclass`` field to keep
+track of the document's corresponding class name, which allows you to
+deserialize the document into a ``Person`` object.
+
 .. note::
 
    You can use the ``Persistable`` interface for root and embedded BSON documents
@@ -227,7 +235,7 @@ You can serialize and deserialize backed enums into BSON data. Backed
 enum values serialize as their case value, while pure enums without
 case values cannot be directly serialized. To perform these conversions,
 you must specify serialization logic by defining the ``bsonSerialize()``
-and ``bsonUnserialize()`` methods.
+and ``bsonUnserialize()`` methods in your class definition.
 
 .. tip::
 
@@ -243,14 +251,15 @@ methods:
 
 .. literalinclude:: /includes/bson.php
     :language: php
+    :emphasize-lines: 15, 24
     :dedent:
     :start-after: start-backed-enum
     :end-before: end-backed-enum
 
 .. note::
 
    Enums cannot implement the ``MongoDB\BSON\Unserializable`` and
-   ``MongoDB\BSON\Persistable`` interfaces, since enum cases have no
+   ``MongoDB\BSON\Persistable`` interfaces because enum cases have no
    state and cannot be instantiated like class objects. However, pure and backed
    enums can implement ``MongoDB\BSON\Serializable``, which you can use to
    override the default enum serialization behavior.

source/includes/bson.php

@@ -14,13 +14,13 @@
     ],
     'coord' => [-73.982419, 41.579505],
     'cuisine' => 'Pizza',
-    'name' => 'Mongo\'s Pizza'
+    'name' => 'Planet Pizza'
 ];
 // end-create-doc
 
 // start-modify-doc
 $document['restaurant_id'] = 12345;
-$document['name'] = 'Mongo\'s Pizza Place';
+$document['name'] = 'Galaxy Pizza';
 // end-modify-doc
 
 // start-type-map