Custom Data-Types

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 DateTimeImmutable class 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\Persistable interface. If a class implements this interface, then upon serialization the 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 MongoDB\BSON\UTCDateTime data 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\Persistable interface, the class is required to implement the bsonSerialize and bsonUnserialize methods. In the 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 MongoDB\BSON\UTCDateTime object, 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::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.

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

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 DateTime object with the local time zone set, instead of the UTC time zone that MongoDB\BSON\UTCDateTime normally 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.