Modelagem de dados BSON

Tipo Maps

A maioria dos métodos que lêem dados do MongoDB suporta uma opção typeMap , que permite o controle sobre como o BSON é convertido em PHP. Além disso, as classes MongoDB\Client, MongoDB\Database e MongoDB\Collection aceitam uma opção typeMap , que pode ser usada para especificar um mapa de tipos padrão a ser aplicado a quaisquer métodos de suporte e classes selecionadas (por exemplo MongoDB\Client::selectDatabase()).

As classes MongoDB\Client, MongoDB\Database e MongoDB\Collection usam o seguinte mapa de tipos por padrão:

[
    'array' => 'MongoDB\Model\BSONArray',
    'document' => 'MongoDB\Model\BSONDocument',
    'root' => 'MongoDB\Model\BSONDocument',
]

O mapa de tipos acima converterá documentos e arrays BSON em objetos MongoDB\Model\BSONDocument e MongoDB\Model\BSONArray , respectivamente. As chaves root e document são usadas para distinguir o documento BSON de nível superior dos documentos incorporados, respectivamente.

Um mapa de tipo pode especificar qualquer classe que implemente MongoDB\BSON\Unserializable bem como "array", "stdClass" e "object" ("stdClass" e "object" são nomes alternativos um do outro).

Classes persistentes

A especificação de persistência do driver descreve como as classes que implementam sua MongoDB\BSON\Persistable interface são serializados e desserializados do BSON. O persistente a interface é análoga à interface serializáveldo PHP .

O driver lida automaticamente com a serialização e a desserialização para as classes que implementam o método Persistable interface sem exigir o uso da typeMap opção . Isso é feito codificando o nome da classe PHP em uma propriedade especial dentro do documento BSON.

Considere a seguinte definição de classe:

<?php
class Person implements MongoDB\BSON\Persistable
{
    private MongoDB\BSON\ObjectId $id;
    private string $name;
    private MongoDB\BSON\UTCDateTime $createdAt;
    public function __construct(string $name)
    {
        $this->id = new MongoDB\BSON\ObjectId;
        $this->name = $name;
        $this->createdAt = new MongoDB\BSON\UTCDateTime;
    }
    function bsonSerialize()
    {
        return [
            '_id' => $this->id,
            'name' => $this->name,
            'createdAt' => $this->createdAt,
        ];
    }
    function bsonUnserialize(array $data)
    {
        $this->id = $data['_id'];
        $this->name = $data['name'];
        $this->createdAt = $data['createdAt'];
    }
}

O exemplo a seguir constrói um objeto Person , insere-o no banco de dados e o lê de volta como um objeto do mesmo tipo:

<?php
$collection = (new MongoDB\Client)->test->persons;
$result = $collection->insertOne(new Person('Bob'));
$person = $collection->findOne(['_id' => $result->getInsertedId()]);
var_dump($person);

A saída seria então semelhante a:

object(Person)#18 (3) {
  ["id":"Person":private]=>
  object(MongoDB\BSON\ObjectId)#15 (1) {
    ["oid"]=>
    string(24) "56fad2c36118fd2e9820cfc1"
  }
  ["name":"Person":private]=>
  string(3) "Bob"
  ["createdAt":"Person":private]=>
  object(MongoDB\BSON\UTCDateTime)#17 (1) {
    ["milliseconds"]=>
    int(1459278531218)
  }
}

O mesmo documento na shell MongoDB pode ser exibido como:

{
  "_id" : ObjectId("56fad2c36118fd2e9820cfc1"),
  "__pclass" : BinData(128,"UGVyc29u"),
  "name" : "Bob",
  "createdAt" : ISODate("2016-03-29T19:08:51.218Z")
}

Trabalhando com Enums

Enums apoiados podem ser usados com BSON e serão serializados como seu valor de caso (ou seja, inteiro ou string). Enums puros, que não têm casos apoiados, não podem ser serializados diretamente. Isto é semelhante a como os enums são manipulados por json_encode().

A ida e volta de uma enumeração apoiada por BSON requer cuidado especial. No exemplo seguinte, o método bsonUnserialize() na classe que contém a enumeração é responsável por converter o valor de volta para um caso de enumeração:

<?php
enum Role: int
{
    case USER = 1;
    case ADMIN = 2;
}
class User implements MongoDB\BSON\Persistable
{
    public function __construct(
        private string $username,
        private Role $role,
        private MongoDB\BSON\ObjectId $_id = new MongoDB\BSON\ObjectId(),
    ) {}
    public function bsonSerialize(): array
    {
        return [
            '_id' => $this->_id,
            'username' => $this->username,
            'role' => $this->role,
        ];
    }
    public function bsonUnserialize(array $data): void
    {
        $this->_id = $data['_id'];
        $this->username = $data['username'];
        $this->role = Role::from($data['role']);
    }
}

Os enums estão proibidos de implementar MongoDB\BSON\Unserializable e MongoDB\BSON\Persistable, já que os casos enum não têm estado e não podem ser instanciados como objetos comuns. No entanto, os enums puros e apoiados podem implementar MongoDB\BSON\Serializable, que pode ser usado para ultrapassar o comportamento padrão pelo qual os enums apoiados são serializados como seu valor de caso e os enums puros não podem ser serializados.