Desserialização do BSON

A extensão mongo herdada desserializou documentos BSON e arrays como arrays PHP. Embora arrays PHP sejam c onvenientes para trabalhar, esse comportamento era problemático porque diferentes tipos de BSON poderiam desserializar para o mesmo valor PHP (por exemplo, {"0": "foo"} e ["foo"]) e torna impossível inferir o tipo BSON original. Por padrão, a extensão mongodb aborda essa preocupação garantindo que arrays e documentos BSON sejam convertidos em arrays e objetos PHP, respectivamente.

Para tipos compostos, existem três tipos de dados:

root

refere-se ao documento BSON de nível superior apenas

document

refere-se a documentos BSON incorporados apenas

array

refere-se a um array BSON

Além dos três tipos de coletivos, também é possível configurar campos específicos em seu documento para mapear os tipos de dados mencionados abaixo. Como exemplo, o seguinte mapa de tipos permite a você mapear cada documento incorporado dentro de um array "addresses" para uma classe Address e cada "city" dentro desses documentos de endereço incorporados para uma classe City:

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

Cada um desses três tipos de dados, bem como os mapeamentos específicos de campo, podem ser mapeados em diferentes tipos de PHP. Os possíveis valores de mapeamento são:

não definido ou NULL (padrão)

• Um array BSON será desserializado como um array PHP.

• Um documento BSON (raiz ou incorporado) sem uma propriedade __pclass ^[1] torna-se um objeto PHP stdClass, com cada chave de documento BSON definida como uma propriedade pública stdClass.

• Um documento BSON (raiz ou incorporado) com uma propriedade __pclass ^[1] torna-se um objeto PHP com o nome da classe conforme definido pela propriedade __pclass.

  Se a classe nomeada implementar a interface MongoDB\BSON\Persistable, então as propriedades do documento BSON, incluindo a propriedade __pclass, serão enviadas como um array associativo para a função MongoDB\BSON\Unserializable::bsonUnserialize() para inicializar as propriedades do objeto.

  Se a classe nomeada não existir ou não implementar a interface MongoDB\BSON\Persistable, stdClass será usada e cada chave de documento BSON (incluindo __pclass) será definido como uma propriedade pública stdClass.

  A funcionalidade __pclass depende da propriedade fazer parte de um documento MongoDB recuperado. Se você usar uma projeção ao consultar documentos, será necessário incluir o campo __pclass na projeção para esta funcionalidade trabalhar.

"array"

Transforma um array BSON ou documento BSON em um array PHP. Não haverá tratamento especial para uma propriedade __pclass ^[1], mas ela poderá ser definida como um elemento no array retornado se estiver presente no documento BSON.

"object" ou "stdClass"

Transforma um array BSON ou documento BSON em um objeto stdClass. Não haverá tratamento especial para uma propriedade __pclass ^[1], mas ela poderá ser definida como uma propriedade pública no objeto retornado se estiver presente no documento BSON.

"bson"

Transforma um array BSON em um MongoDB\BSON\PackedArray e um documento BSON em um MongoDB\BSON\Document, independentemente de o documento BSON ter uma propriedade __pclass ^[1].

Nota: O valor bson está disponível apenas para os três tipos de raiz, não nos mapeamentos específicos do campo.

qualquer outra string

Define o nome da classe como um array BSON ou o objeto BSON deve ser desserializado. Para objetos BSON que incluem propriedades __pclass, essa classe terá prioridade.

Se a classe nomeada não existir, não for concreta (ou seja, for abstrata ou uma interface) ou não implementar MongoDB\BSON\Unserializable então uma exceção MongoDB\Driver\Exception\InvalidArgumentException é lançada.

Se o objeto BSON tiver uma propriedade __pclass e essa classe existir e implementar MongoDB\BSON\Persistable ela substituirá a classe fornecida no mapa de tipos.

As propriedades do documento BSON, incluindo a propriedade __pclass se existir, serão enviadas como um array associativo para a função MongoDB\BSON\Unserializable::bsonUnserialize() para inicializar as propriedades do objeto.

/* typemap: [] (all defaults) */
{ "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") }