PHPLIB-341: Add LocalDateTime example to tutorial

docs/tutorial.txt

@@ -8,6 +8,7 @@ Tutorials
    /tutorial/crud
    /tutorial/collation
    /tutorial/commands
+   /tutorial/custom-types
    /tutorial/decimal128
    /tutorial/gridfs
    /tutorial/indexes

docs/tutorial/custom-types.txt

+=================
+Custom Data-Types
+=================
+
+.. default-domain:: mongodb
+
+The MongoDB PHP extension and library support custom classes while
+serializing and deserializing. An example of where this might be useful is
+if you want to store date/time information retaining the time zone
+information that PHP's :php:`DateTimeImmutable <class.datetimeimmutable>`
+class stores with a point in time.
+
+The driver serializes PHP variables, including objects, into BSON when it
+communicates to the server, and deserializes BSON back into PHP variables when
+it receives data from the server.
+
+It is possible to influence the behaviour by implementing the
+:php:`MongoDB\\BSON\\Persistable <class.mongodb-bson-persistable>` interface.
+If a class implements this interface, then upon serialization the
+:php:`bsonSerialize <mongodb-bson-serializable.bsonserialize>` method is
+called. This method is responsible for returning an array or stdClass object
+to convert to BSON and store in the database. That data will later be used to
+reconstruct the object upon reading from the database.
+
+As an example we present the ``LocalDateTime`` class. This class wraps around
+the :php:`MongoDB\\BSON\UTCDateTime <class.mongodb-bson-utcdatetime>` data
+type and a time zone.
+
+.. code-block:: php
+
+    <?php
+    /* Custom document class that stores a UTCDateTime and time zone and also
+     * implements the UTCDateTime interface for portability. */
+    class LocalDateTime implements \MongoDB\BSON\Persistable, \MongoDB\BSON\UTCDateTimeInterface
+    {
+        private $utc;
+        private $tz;
+        public function __construct($milliseconds = null, \DateTimeZone $timezone = null)
+        {
+            $this->utc = new \MongoDB\BSON\UTCDateTime($milliseconds);
+            if ($timezone === null) {
+                $timezone = new \DateTimeZone(date_default_timezone_get());
+            }
+            $this->tz = $timezone;
+        }
+    ?>
+
+As it implements the :php:`MongoDB\\BSON\\Persistable
+<class.mongodb-bson-persistable>` interface, the
+class is required to implement the :php:`bsonSerialize
+<mongodb-bson-serializable.bsonserialize>` and :php:`bsonUnserialize
+<mongodb-bson-unserializable.bsonunserialize>` methods. In the
+:php:`bsonSerialize <mongodb-bson-serializable.bsonserialize>` method, we
+return an array with the two values that we need to persist: the point in time
+in milliseconds since the Epoch, represented by a
+:php:`MongoDB\\BSON\\UTCDateTime <class.mongodb-bson-utcdatetime>` object, and
+a string containing the Olson time zone identifier:
+
+.. code-block:: php
+
+    <?php
+        public function bsonSerialize()
+        {
+            return [
+                'utc' => $this->utc,
+                'tz' => $this->tz->getName(),
+            ];
+        }
+    ?>
+
+The driver will additionally add a ``__pclass`` field to the document, and
+store that in the database, too. This field contains the PHP class name so that
+upon deserialization the driver knows which class to use for recreating the
+stored object.
+
+When the document is read from the database, the driver detects whether a
+``__pclass`` field is present and then executes
+:php:`MongoDB\\BSON\\Persistable::bsonUnserialize
+<mongodb-bson-unserializable.bsonunserialize>` method which is
+responsible for restoring the object's original state.
+
+In the code below, we make sure that the data in the ``utc`` and ``tz`` fields
+are of the right time, and then assign their values to the two private
+properties.
+
+.. code-block:: php
+
+    <?php
+        public function bsonUnserialize(array $data)
+        {
+            if ( ! isset($data['utc']) || ! $data['utc'] instanceof \MongoDB\BSON\UTCDateTime) {
+                throw new Exception('Expected "utc" field to be a UTCDateTime');
+            }
+
+            if ( ! isset($data['tz']) || ! is_string($data['tz'])) {
+                throw new Exception('Expected "tz" field to be a string');
+            }
+
+            $this->utc = $data['utc'];
+            $this->tz = new \DateTimeZone($data['tz']);
+        }
+    ?>
+
+You may have noticed that the class also implements the
+:php:`MongoDB\\BSON\\UTCDateTimeInterface
+<class.mongodb-bson-utcdatetimeinterface>` interface. This interface defines
+the two non-constructor methods of the :php:`MongoDB\\BSON\\UTCDateTime
+<class.mongodb-bson-utcdatetime>` class.
+
+It is recommended that wrappers around existing BSON classes implement their
+respective interface (i.e. :php:`MongoDB\\BSON\\UTCDateTimeInterface
+<class.mongodb-bson-utcdatetimeinterface>`) so that the wrapper objects can be
+used in the same context as their original unwrapped version. It is also
+recommended that you always type-hint against the interface (i.e.
+:php:`MongoDB\\BSON\\UTCDateTimeInterface
+<class.mongodb-bson-utcdatetimeinterface>`) and never against the concrete
+class (i.e. :php:`MongoDB\\BSON\\UTCDateTime
+<class.mongodb-bson-utcdatetime>`), as this would prevent wrapped objects from
+being accepted into methods.
+
+In our new ``toDateTime`` method we return a :php:`DateTime <class.datetime>`
+object with the local time zone set, instead of the UTC time zone that
+:php:`MongoDB\\BSON\\UTCDateTime <class.mongodb-bson-utcdatetime>` normally uses
+in its return value.
+
+.. code-block:: php
+
+    <?php
+        public function toDateTime()
+        {
+            return $this->utc->toDateTime()->setTimezone($this->tz);
+        }
+
+        public function __toString()
+        {
+            return (string) $this->utc;
+        }
+    }
+    ?>
+
+With the class defined, we can now use it in our documents. The snippet below
+demonstrates the round tripping from the ``LocalDateTime`` object to BSON, and
+back to ``LocalDateTime``.
+
+.. code-block:: php
+
+    <?php
+    $bson = MongoDB\BSON\fromPHP(['date' => new LocalDateTime]);
+    $document = MongoDB\BSON\toPHP($bson);
+
+    var_dump($document);
+    var_dump($document->date->toDateTime());
+    ?>
+
+Which outputs::
+
+    object(stdClass)#1 (1) {
+      ["date"]=>
+      object(LocalDateTime)#2 (2) {
+        ["utc":"LocalDateTime":private]=>
+        object(MongoDB\BSON\UTCDateTime)#3 (1) {
+          ["milliseconds"]=>
+          string(13) "1533042443716"
+        }
+        ["tz":"LocalDateTime":private]=>
+        object(DateTimeZone)#4 (2) {
+          ["timezone_type"]=>
+          int(3)
+          ["timezone"]=>
+          string(13) "Europe/London"
+        }
+      }
+    }
+    object(DateTime)#5 (3) {
+      ["date"]=>
+      string(26) "2018-07-31 14:07:23.716000"
+      ["timezone_type"]=>
+      int(3)
+      ["timezone"]=>
+      string(13) "Europe/London"
+    }
+
+Storing the Olson time zone identifier in a separate field also works well
+with MongoDB's :manual:`Aggregation Framework </aggregation>`, which allows
+date manipulation, :manual:`formatting
+</reference/operator/aggregation/dateToString>`, and querying depending on a
+specific time zone.