PHP Classes

File: vendor/mongodb/mongodb/docs/tutorial/custom-types.txt

Recommend this page to a friend!
  Classes of walid laggoune   MongoDB Queue PHP Query Execute   vendor/mongodb/mongodb/docs/tutorial/custom-types.txt   Download  
File: vendor/mongodb/mongodb/docs/tutorial/custom-types.txt
Role: Documentation
Content type: text/plain
Description: Documentation
Class: MongoDB Queue PHP Query Execute
Query and execute multiple queries using MongoDB
Author: By
Last change:
Date: 4 years ago
Size: 6,835 bytes
 

Contents

Class file image Download
================= 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.