/ /

Trabajar con datos BSON

Overview

En esta guía, puede aprender a crear e interactuar con documentos BSON utilizando la biblioteca PHP.

BSON, o JSON binario, es el formato de datos que MongoDB utiliza para organizar y almacenar datos. Este formato incluye todos los tipos de estructuras de datos JSON y también admite otros tipos, como fechas y números enteros de diferentes tamaños. ObjectId valores y datos binarios. La biblioteca PHP proporciona MongoDB\Model\BSONArray Tipos y para almacenar datos BSON.MongoDB\Model\BSONDocument

Tip

Para ver una lista completa de los tipos BSON admitidos, consulte Tipos BSON en el manual del servidor MongoDB.

Datos de muestra

Los ejemplos de código en esta guía hacen referencia al siguiente documento BSON de muestra:

{
    "address" : {
        "street" : "Pizza St",
        "zipcode" : "10003"
    },
    "coord" : [-73.982419, 41.579505]
    "cuisine" : "Pizza",
    "name" : "Planet Pizza"
}

Crear un documento BSON

Puedes crear un documento BSON usando la misma notación que para crear un array asociativo en PHP. La biblioteca PHP convierte automáticamente estos valores en documentos BSON al insertarlos en una colección.

El siguiente ejemplo crea un documento BSON que representa el documento BSON de muestra anterior:

$document = [
    'address' => [
        'street' => 'Pizza St',
        'zipcode' => '10003',
    ],
    'coord' => [-73.982419, 41.579505],
    'cuisine' => 'Pizza',
    'name' => 'Planet Pizza',
];

Cambiar un documento BSON

Puede modificar el contenido de un documento BSON utilizando la misma notación que utiliza para modificar una matriz asociativa en PHP. Este ejemplo realiza los siguientes cambios en el documento BSON de ejemplo:

Agrega un nuevo campo restaurant_id que tiene un valor de 12345
Cambia el valor del campo name a "Galaxy Pizza"

$document['restaurant_id'] = 12345;
$document['name'] = 'Galaxy Pizza';

Nota

El código anterior solo modifica los valores en memoria del documento BSON de ejemplo. No ejecuta ninguna operación de base de datos que modifique los valores almacenados en MongoDB. Para saber cómo modificar documentos almacenados en MongoDB, consulte la guía "Actualizar documentos".

Personalizar la serialización BSON

Las siguientes secciones describen cómo configurar la forma en que su aplicación serializa datos BSON:

Mapas de tipos: utilice la typeMap opción para especificar la conversión predeterminada entre tipos PHP y tipos BSON.
Clases persistentes: utilice la MongoDB\BSON\Persistable interfaz para habilitar la serialización.
Valores de enumeración: utilice los bsonSerialize() bsonUnserialize() métodos y para especificar la serialización entre enumeraciones respaldadas y valores BSON.

Mapas de tipos

Puede configurar la opción typeMap, que configura la serialización y deserialización entre valores PHP y BSON, en los siguientes niveles:

MongoDB\Client, que establece el valor predeterminado para todas las operaciones a menos que se anule
MongoDB\Database
MongoDB\Collection

Esta lista también indica el orden de precedencia creciente de las opciones. Por ejemplo, si se establece un typeMap para una colección, se anulará el mapa de tipos establecido en la base de datos.

La biblioteca PHP utiliza el siguiente mapa de tipos de forma predeterminada:

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

Este tipo de mapa realiza las siguientes conversiones en ambas direcciones:

Matrices de MongoDB\Model\BSONArray objetos
Documentos BSON de nivel superior e incrustados en objetos MongoDB\Model\BSONDocument

Un mapa de tipos puede especificar cualquier clase que implemente MongoDB\BSON\Unserializableinterfaz. También puede especificar conversiones de los array stdClass object tipos, y.

Ejemplo de mapa de tipo personalizado

El siguiente ejemplo establece la opción typeMap para la colección restaurants que serializa matrices y documentos BSON como objetos MongoDB\Model\BSONDocument:

$options = [
    'typeMap' => [
        'array' => 'MongoDB\Model\BSONDocument',
        'root' => 'MongoDB\Model\BSONDocument',
        'document' => 'MongoDB\Model\BSONDocument',
    ],
];
$db->createCollection('restaurants', $options);

Clases persistentes

Puede crear clases que implementen la interfaz MongoDB\BSON\Persistable. Esta interfaz indica a la biblioteca PHP que realice automáticamente la serialización y deserialización según la especificación de persistencia de la extensión PHP, sin requerir la typeMap opción. La Persistable interfaz es análoga a la interfaz Serializable de PHP.

Al deserializar una variable PHP desde BSON, el nombre de clase codificado de un objeto Persistable anula cualquier clase especificada en la opción typeMap. Sin embargo, no anula los tipos array, stdClass ni object.

Ejemplo

Considere la siguiente definición de clase Person, que implementa la interfaz Persistable y especifica cómo serializar y deserializar campos de objeto como valores BSON:

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

El siguiente ejemplo construye un objeto Person, lo inserta en la base de datos y lo lee de nuevo como un objeto del mismo tipo:

$collection = $client->test->persons;
$result = $collection->insertOne(new Person('Bob'));
$person = $collection->findOne(['_id' => $result->getInsertedId()]);
var_dump($person);

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)
    }
}

El documento devuelto es equivalente al siguiente documento BSON:

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

La biblioteca PHP agrega automáticamente el campo __pclass para realizar un seguimiento del nombre de clase correspondiente del documento, lo que le permite deserializar el documento en un objeto Person.

Nota

Puede utilizar la interfaz Persistable únicamente para documentos BSON raíz e incrustados, no para matrices BSON.

Enum Values

Puede serializar y deserializar enumeraciones respaldadas en datos BSON. Los valores de enumeración respaldados se serializan como su valor de caso, mientras que las enumeraciones puras sin valores de caso no se pueden serializar directamente. Para realizar estas conversiones, debe especificar la lógica de serialización definiendo los métodos bsonSerialize() y bsonUnserialize() en la definición de la clase.

Tip

Para obtener más información sobre enumeraciones respaldadas, consulte Enumeraciones respaldadas en la documentación de la extensión PHP.

Ejemplo

Considera el siguiente enum respaldado llamado Role, que tiene dos casos con valores enteros:

enum Role: int
{
    case USER = 1;
    case ADMIN = 2;
}

Esta definición de clase User incluye un campo role con un valor de enumeración Role y especifica la lógica para serializar y deserializar sus campos en valores BSON:

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']);
    }
}

El siguiente ejemplo construye un objeto User con un campo role, lo inserta en la base de datos y lo vuelve a leer como un objeto del mismo tipo:

$collection = $client->test->users;
$result = $collection->insertOne(new User('alice', Role::USER));
$person = $collection->findOne(['_id' => $result->getInsertedId()]);
var_dump($person);

object(User)#40 (3) {
   ["username":"User":private]=>
   string(5) "alice"
   ["role":"User":private]=>
   enum(Role::USER)
   ["_id":"User":private]=>
   object(MongoDB\BSON\ObjectId)#38 (1) {
      ["oid"]=>
      string(24) "..."
   }
}

Nota

Las enumeraciones no pueden implementar las interfaces MongoDB\BSON\Unserializable y MongoDB\BSON\Persistable porque los casos de enumeración no tienen estado y no se pueden instanciar como objetos de clase. Sin embargo, las enumeraciones puras y respaldadas sí pueden implementar MongoDB\BSON\Serializable, lo cual permite anular el comportamiento predeterminado de serialización de enumeraciones.

Documentación de la API

Para obtener más información sobre cualquiera de los métodos o tipos de biblioteca PHP analizados en esta guía, consulte la siguiente documentación de la API de la biblioteca:

Para obtener más información sobre los tipos de extensión PHP analizados en esta guía, consulte la siguiente documentación de la API de extensión:

Volver

Decimal128

Time Series