Este documento discute como estruturas compostas (ou seja, documentos, arrays e objetos) são convertidas entre valores BSON e PHP.
Se um array for um array compactado - ou seja, um array vazio ou as chaves começam em 0 e são sequenciais sem lacunas: array BSON.
Se o array não estiver compactado - ou seja, tiver chaves associativas (string), as chaves não começam em 0 ou quando há lacunas:: objeto BSON
Um documento de nível superior (raiz), sempre serializa como um documento BSON.
Estes são serializados como um array BSON:
[ 8, 5, 2, 3 ] => [ 8, 5, 2, 3 ] [ 0 => 4, 1 => 9 ] => [ 4, 9 ]
Estes são serializados como um documento BSON:
[ 0 => 1, 2 => 8, 3 => 12 ] => { "0" : 1, "2" : 8, "3" : 12 } [ "foo" => 42 ] => { "foo" : 42 } [ 1 => 9, 0 => 10 ] => { "1" : 9, "0" : 10 }
Observe que os cinco exemplos são extraídos de um documento completo e representam apenas um valor dentro de um documento.
Se um objeto for da classe stdClass, serialize como um documento BSON.
Se um objeto for de uma classe suportada que implementa MongoDB\BSON\Type, use a lógica de serialização BSON para esse tipo específico. Instâncias MongoDB\BSON\Type, excluindo MongoDB\BSON\Serializable, só podem ser serializadas como um valor de campo de documento. Tentar serializar tal objeto como um documento raiz lançará uma exceção MongoDB\Driver\Exception\UnexpectedValueException
Se um objeto for de uma classe desconhecida que implementa a interface MongoDB\BSON\Type, lance uma exceção MongoDB\Driver\Exception\UnexpectedValueException
Se um objeto for de qualquer outra classe, sem implementar nenhuma interface especial, serialize como um documento BSON. Mantenha apenas propriedades públicas e ignore propriedades protegidas e privadas.
Se um objeto for de uma classe que implementa a interface MongoDB\BSON\Serializable, chame MongoDB\BSON\Serializable::bsonSerialize() e use o array retornado ou stdClass para serializar como um documento ou array BSON. O tipo BSON será determinado pelo seguinte:
Os documentos raiz devem ser serializados como um documento BSON.
Os objetos MongoDB\BSON\Persistable devem ser serializados como um documento BSON.
Se MongoDB\BSON\Serializable::bsonSerialize() retornar um array compactado, serialize como um array BSON.
Se MongoDB\BSON\Serializable::bsonSerialize() retornar um array não compactado ou stdClass, serialize como um documento BSON.
Se MongoDB\BSON\Serializable::bsonSerialize() não retornou uma matriz ou stdClass, lance uma exceção MongoDB\Driver\Exception\UnexpectedValueException.
Se um objeto for de uma classe que implementa a
interface MongoDB\BSON\Persistable (o que
implica MongoDB\BSON\Serializable), obtenha
as propriedades de maneira semelhante à parágrafos anteriores, mas
também adicione uma propriedade adicional
__pclass como um valor binário, com subtipo
0x80
e dados contendo o nome completo da classe do objeto
que está sendo serializado.
A propriedade __pclass é adicionada ao array ou objeto retornado por MongoDB\BSON\Serializable::bsonSerialize(), o que significa que ela substituirá qualquer chave/propriedade __pclass no valor de retorno MongoDB\BSON\Serializable::bsonSerialize(). Se você quiser evitar esse comportamento e definir seu próprio valor __pclass, você não deve implementar MongoDB\BSON\Persistable e, em vez disso, deve implementar MongoDB\BSON\Serializable diretamente.
<?php
class stdClass
{
public $foo = 42;
} // => {"foo": 42}
class MyClass
{
public $foo = 42;
protected $prot = 'wine';
private $fpr = 'cheese';
} // => {"foo": 42}
class AnotherClass1 implements MongoDB\BSON\Serializable
{
public $foo = 42;
protected $prot = 'wine';
private $fpr = 'cheese';
public function bsonSerialize(): array
{
return ['foo' => $this->foo, 'prot' => $this->prot];
}
} // => {"foo": 42, "prot": "wine"}
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"}
/**
* Nesting Serializable classes
*/
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 = 'wine';
private $fpr = 'cheese';
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": "wine", "__pclass": {"$type": "80", "$binary": "VXBwZXJDbGFzcw=="}}
?>
Os documentos BSON tecnicamente podem conter chaves duplicadas porque os documentos são armazenados como uma lista de pares chave-valor; no entanto, as aplicações devem evitar a geração de documentos com chaves duplicadas, pois o comportamento do servidor e do driver pode ser indefinido. Como os objetos e arrays do PHP não podem ter chaves duplicadas, os dados também podem ser perdidos ao decodificar um documento BSON com chaves duplicadas.
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:
refere-se ao documento BSON de nível superior apenas
refere-se a documentos BSON incorporados apenas
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:
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.
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.
TypeMaps podem ser definidos através do
método MongoDB\Driver\Cursor::setTypeMap() em um
objeto MongoDB\Driver\Cursor ou do
argumento $typeMap
de
MongoDB\BSON\toPHP(),
MongoDB\BSON\Document::toPHP() e
MongoDB\BSON\PackedArray::toPHP(). Cada uma das três
classes (root, document e
array) pode ser definida individualmente, além dos tipos
específicos de campo.
Se o valor no mapa for NULL, significa o mesmo que o valor padrão para esse item.
Esses exemplos usam as seguintes classes:
que não implementa nenhuma interface
que implementa MongoDB\BSON\Unserializable
que implementa MongoDB\BSON\Persistable
que estende OurClass
O método MongoDB\BSON\Unserializable::bsonUnserialize()
de YourClass, OurClass, TheirClass itera sobre o array e define
as propriedades sem modificações. Ele também define
a propriedade $unserialized
como true
:
<?php
function bsonUnserialize( array $map )
{
foreach ( $map as $k => $value )
{
$this->$k = $value;
}
$this->unserialized = true;
}
/* 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") }