Custom Data-Types

Note

This tutorial explains implementing custom data types using the

MongoDB\BSON\Persistableinterface found in the MongoDB extension. Consider using a codec instead to decouple the MongoDB persistence logic from your business logic. See thecodec tutorial for an example.

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 DateTimeImmutableclass stores with a point in time.

The extension 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 behavior by implementing the MongoDB\BSON\Persistableinterface. If a class implements this interface, then upon serialization the bsonSerializemethod 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 MongoDB\BSON\UTCDateTimedata type and a time zone.

<?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 MongoDB\BSON\Persistableinterface, the class is required to implement the bsonSerializeand bsonUnserializemethods. In the bsonSerializemethod, 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 MongoDB\BSON\UTCDateTimeobject, and a string containing the Olson time zone identifier:

<?php
    public function bsonSerialize()
    {
        return [
            'utc' => $this->utc,
            'tz' => $this->tz->getName(),
        ];
    }
?>

The extension 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 extension knows which class to use for recreating the stored object.

When the document is read from the database, the extension detects whether a __pclass field is present and then executes MongoDB\BSON\Persistable::bsonUnserializemethod 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.

<?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 MongoDB\BSON\UTCDateTimeInterfaceinterface. This interface defines the two non-constructor methods of the MongoDB\BSON\UTCDateTimeclass.

It is recommended that wrappers around existing BSON classes implement their respective interface (i.e. 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. MongoDB\BSON\UTCDateTimeInterface) and never against the concrete class (i.e. MongoDB\BSON\UTCDateTime), as this would prevent wrapped objects from being accepted into methods.

In our new toDateTime method we return a DateTimeobject with the local time zone set, instead of the UTC time zone that MongoDB\BSON\UTCDateTimenormally uses in its return value.

<?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.

<?php
$bson = MongoDB\BSON\Document::fromPHP(['date' => new LocalDateTime]);
$document = $bson->toPHP();
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 Aggregation Framework, which allows date manipulation, formatting, and querying depending on a specific time zone.

Back

Specialized Data Formats

Codecs