Сериализация в BSON

[8, 5, 2, 3] => [8, 5, 2, 3]
[0 => 4, 1 => 9] => [4, 9]

[0 => 1, 2 => 8, 3 => 12] => {"0": 1, "2": 8, "3": 12}
["foo" => 42] => {"foo": 42}
[1 => 9, 0 => 10] => {"1": 9, "0": 10}

<?php

class stdClass
{
    public $foo = 42;
} // => {"foo": 42}

class MyClass
{
    public $foo = 42;
    protected $prot = 'вино';
    private $fpr = 'сыр';
} // => {"foo": 42}

class AnotherClass1 implements MongoDB\BSON\Serializable
{
    public $foo = 42;
    protected $prot = 'вино';
    private $fpr = 'сыр';

    public function bsonSerialize(): array
    {
        return ['foo' => $this->foo, 'prot' => $this->prot];
    }
} // => {"foo": 42, "prot": "вино"}

class AnotherClass2 implements MongoDB\BSON\Serializable
{
    public $foo = 42;

    public function bsonSerialize(): self
    {
        return $this;
    }
} // => MongoDB\Driver\Exception\UnexpectedValueException("bsonSerialize() did not return an array or stdClass")

class AnotherClass3 implements MongoDB\BSON\Serializable
{
    private $elements = ['foo', 'bar'];

    public function bsonSerialize(): array
    {
        return $this->elements;
    }
} // => {"0": "foo", "1": "bar"}

/**
 * Вложенные сериализуемые классы
 */

class AnotherClass4 implements MongoDB\BSON\Serializable
{
    private $elements = [0 => 'foo', 2 => 'bar'];

    public function bsonSerialize(): array
    {
        return $this->elements;
    }
} // => {"0": "foo", "2": "bar"}

class ContainerClass1 implements MongoDB\BSON\Serializable
{
    public $things;

    public function __construct()
    {
        $this->things = new AnotherClass4();
    }

    function bsonSerialize(): array
    {
        return ['things' => $this->things];
    }
} // => {"things": {"0": "foo", "2": "bar"}}


class AnotherClass5 implements MongoDB\BSON\Serializable
{
    private $elements = [0 => 'foo', 2 => 'bar'];

    public function bsonSerialize(): array
    {
        return array_values($this->elements);
    }
} // => {"0": "foo", "1": "bar"} as a root class
  //    ["foo", "bar"] as a nested value

class ContainerClass2 implements MongoDB\BSON\Serializable
{
    public $things;

    public function __construct()
    {
        $this->things = new AnotherClass5();
    }

    public function bsonSerialize(): array
    {
        return ['things' => $this->things];
    }
} // => {"things": ["foo", "bar"]}


class AnotherClass6 implements MongoDB\BSON\Serializable
{
    private $elements = ['foo', 'bar'];

    function bsonSerialize(): object
    {
        return (object) $this->elements;
    }
} // => {"0": "foo", "1": "bar"}

class ContainerClass3 implements MongoDB\BSON\Serializable
{
    public $things;

    public function __construct()
    {
        $this->things = new AnotherClass6();
    }

    public function bsonSerialize(): array
    {
        return ['things' => $this->things];
    }
} // => {"things": {"0": "foo", "1": "bar"}}

class UpperClass implements MongoDB\BSON\Persistable
{
    public $foo = 42;
    protected $prot = 'вино';
    private $fpr = 'сыр';

    private $data;

    public function bsonUnserialize(array $data): void
    {
        $this->data = $data;
    }

    public function bsonSerialize(): array
    {
        return ['foo' => $this->foo, 'prot' => $this->prot];
    }
} // => {"foo": 42, "prot": "вино", "__pclass": {"$type": "80", "$binary": "VXBwZXJDbGFzcw=="}}

?>

Десериализация из BSON

Устаревший модуль mongo десериализовывал BSON-документы и BSON-массивы в PHP-массивы. Хотя с PHP-массивами удобно работать, такое поведение было проблематичным, поскольку разные BSON-типы могли десериализоваться до одного и того же PHP-значения (например, {"0": "foo"} и ["foo"]), что делало невозможным определение оригинального BSON-типа. По умолчанию модуль mongodb решает эту проблему и гарантирует, что BSON-массивы преобразуются в PHP-массивы, а BSON-документы в PHP-объекты.

Для составных типов существует три типа данных:

root

относится только к BSON-документу верхнего уровня

document

относится только к встроенным BSON-документам

array

относится к BSON-массивам

Помимо трёх групповых типов, также можно настроить определённые поля в документе для сопоставления с типами данных, как указывает следующий фрагмент кода. В качестве примера, следующая карта типов позволяет сопоставить каждый встроенный документ в массиве «addresses» с классом Address, а каждое поле «city» в этих документах с встроенным адресом с классом City:

[
    'fieldPaths' => [
        'addresses.$' => 'MyProject\Address',
        'addresses.$.city' => 'MyProject\City',
    ],
]

Каждый из этих трёх типов данных, а также сопоставления конкретных полей можно сопоставить с различными типами PHP. Возможные значения сопоставления:

не указано или NULL (по умолчанию)

• BSON-массив будет десериализован как PHP-массив (array).

• BSON-документ (корневой или встроенный) без свойства __pclass ^[1]

  Свойство __pclass считается существующим, только если существует свойство с таким именем, и оно представляет собой Binary-значение, а подтип Binary значения равен 0x80. Если какое-либо из этих трёх условий не выполняется, свойство __pclass не существует и должно рассматриваться как любое другое обычное свойство.

  становится PHP-объектом stdClass, причём каждый ключ BSON-документа устанавливается как открытое свойство объекта stdClass.

• BSON-документ (корневой или встроенный) со свойством __pclass ^[1] становится PHP-объектом имени класса, как это определяет свойство __pclass.

  Если именованный класс реализует интерфейс MMongoDB\BSON\Persistable, то свойства BSON-документа, включая свойство __pclass, отправляются как ассоциативный массив в метод MongoDB\BSON\Unserializable::bsonUnserialize(), чтобы инициализировать свойства объекта.

  Если именованный класс не существует или не реализует интерфейс MongoDB\BSON\Persistable, будет использоваться объект stdClass, и каждый ключ BSON-документа (включая свойство __pclass) будет установлен как открытое свойство объекта stdClass.

  Функциональность свойства __pclass зависит от того, представляет ли собой свойство часть извлечённого документа БД MongoDB. Если при запросе документов используется проекция, необходимо включить в проекцию поле __pclass, чтобы эта функциональность работала.

«array»

Превращает BSON-массив или BSON-документ в PHP-массив. Специальной обработки свойства __pclass ^[1] не будет, но его можно установить как элемент в возвращаемом массиве, если он содержался в BSON-документе.

«object» или «stdClass»

Превращает BSON-массив или BSON-документ в объект stdClass. Специальной обработки свойства __pclass ^[1] не будет, но его можно установить как открытое свойство в возвращаемом объекте, если оно присутствовало в BSON-документе.

«bson»

Превращает BSON-массив в объект MongoDB\BSON\PackedArray, а BSON-документ в объект MongoDB\BSON\Document, независимо от того, есть ли у BSON-документа свойство __pclass ^[1].

Замечание:

Значение bson доступно только для трёх корневых типов, но не в отображениях для конкретных полей.

любая другая строка

Определяет имя класса, который должен десериализовать BSON-массив или BSON-объект. Для BSON-объектов, которые содержат свойства __pclass, этот класс будет приоритетным.

Если именованный класс не существует, не представляет собой конкретный класс (то есть это абстрактный класс или интерфейс) или не реализует интерфейс MongoDB\BSON\Unserializable, выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException.

Если BSON-объект содержит свойство __pclass и этот класс существует и реализует интерфейс MongoDB\BSON\Persistable, он заменит класс, представленный в карте типов.

Свойства BSON-документа, включая свойство __pclass, если оно существует, отправляются как ассоциативный массив в метод MongoDB\BSON\Unserializable::bsonUnserialize(), чтобы инициализировать свойства объекта.

<?php

function bsonUnserialize(array $map)
{
    foreach ($map as $k => $value) {
        $this->$k = $value;
    }
    $this->unserialized = true;
}

?>

/* typemap: [] (все значения по умолчанию) */
{"foo": "yes", "bar" : false}
  -> stdClass {$foo => 'yes', $bar => false}

{"foo": "no", "array" : [5, 6]}
  -> stdClass {$foo => 'no', $array => [5, 6]}

{"foo": "no", "obj" : {"embedded" : 3.14}}
  -> stdClass {$foo => 'no', $obj => stdClass {$embedded => 3.14}}

{"foo": "yes", "__pclass": "MyClass"}
  -> stdClass {$foo => 'yes', $__pclass => 'MyClass'}

{"foo": "yes", "__pclass": {"$type" : "80", "$binary" : "MyClass"}}
  -> stdClass {$foo => 'yes', $__pclass => Binary(0x80, 'MyClass')}

{"foo": "yes", "__pclass": {"$type" : "80", "$binary" : "YourClass")}
  -> stdClass {$foo => 'yes', $__pclass => Binary(0x80, 'YourClass')}

{"foo": "yes", "__pclass": {"$type" : "80", "$binary" : "OurClass")}
  -> OurClass {$foo => 'yes', $__pclass => Binary(0x80, 'OurClass'), $unserialized => true}

{"foo": "yes", "__pclass": {"$type" : "44", "$binary" : "YourClass")}
  -> stdClass {$foo => 'yes', $__pclass => Binary(0x44, 'YourClass')}

/* typemap: ["root" => "MissingClass"] */
{"foo": "yes"}
  -> MongoDB\Driver\Exception\InvalidArgumentException("MissingClass does not exist")

/* typemap: ["root" => "MyClass"] */
{"foo": "yes", "__pclass" : {"$type": "80", "$binary": "MyClass"}}
  -> MongoDB\Driver\Exception\InvalidArgumentException("MyClass does not implement Unserializable interface")

/* typemap: ["root" => "MongoDB\BSON\Unserializable"] */
{"foo": "yes"}
  -> MongoDB\Driver\Exception\InvalidArgumentException("Unserializable is not a concrete class")

/* typemap: ["root" => "YourClass"] */
{"foo": "yes", "__pclass" : {"$type": "80", "$binary": "MongoDB\BSON\Unserializable"}}
  -> YourClass {$foo => "yes", $__pclass => Binary(0x80, "MongoDB\BSON\Unserializable"), $unserialized => true}

/* typemap: ["root" => "YourClass"] */
{"foo": "yes", "__pclass" : {"$type": "80", "$binary": "MyClass"}}
  -> YourClass {$foo => "yes", $__pclass => Binary(0x80, "MyClass"), $unserialized => true}

/* typemap: ["root" => "YourClass"] */
{"foo": "yes", "__pclass" : {"$type": "80", "$binary": "OurClass"}}
  -> OurClass {$foo => "yes", $__pclass => Binary(0x80, "OurClass"), $unserialized => true}

/* typemap: ["root" => "YourClass"] */
{"foo": "yes", "__pclass" : {"$type": "80", "$binary": "TheirClass"}}
  -> TheirClass {$foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true}

/* typemap: ["root" => "OurClass"] */
{ foo: "yes", "__pclass" : {"$type": "80", "$binary": "TheirClass"}}
  -> TheirClass {$foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true}

/* typemap: ['root' => 'YourClass'] */
{foo: "yes", "__pclass": {"$type": "80", "$binary": "YourClass"}}
  -> YourClass {$foo => 'yes', $__pclass => Binary(0x80, 'YourClass'), $unserialized => true}

/* typemap: ['root' => 'array', 'document' => 'array'] */
{"foo": "yes", "bar": false}
  -> ["foo" => "yes", "bar" => false]

{"foo": "no", "array": [5, 6]}
  -> ["foo" => "no", "array" => [5, 6]]

{"foo": "no", "obj": {"embedded": 3.14}}
  -> ["foo" => "no", "obj" => ["embedded => 3.14]]

{"foo": "yes", "__pclass": "MyClass"}
  -> ["foo" => "yes", "__pclass" => "MyClass"]

{"foo": "yes", "__pclass": {"$type": "80", "$binary": "MyClass"}}
  -> ["foo" => "yes", "__pclass" => Binary(0x80, "MyClass")]

{"foo": "yes", "__pclass": {"$type": "80", "$binary": "OurClass"}}
  -> ["foo" => "yes", "__pclass" => Binary(0x80, "OurClass")]

/* typemap: ['root' => 'object', 'document' => 'object'] */
{"foo": "yes", "__pclass": {"$type": "80", "$binary": "MyClass"}}
  -> stdClass {$foo => "yes", "__pclass" => Binary(0x80, "MyClass")}