/ /

Trabajar con datos BSON

Overview

En esta guía, puedes aprender cómo crear e interactuar con documentos BSON utilizando la librería PHP.

BSON, o JSON binario, es el formato de datos que utiliza MongoDB para organizar y almacenar datos. Este formato de datos incluye todos los tipos de estructuras de datos JSON y también soporta otros tipos, incluyendo fechas, 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 BSON types admitidos, consulte BSON types en el manual del MongoDB Server.

Datos de muestra

Los ejemplos de código de 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 utilizando el mismo arreglo que utilizas para crear un arreglo asociativo en PHP. La librería 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 muestraanterior:

$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 se usa para modificar un arreglo asociativo en PHP. Este ejemplo realiza los siguientes cambios en el documento BSON de muestra:

Agrega un nuevo campo de 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 tu aplicación serializa los 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 del enum: Usa los métodos bsonSerialize() y bsonUnserialize() para especificar la serialización entre enums respaldados y valores BSON.

Mapas de tipos

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

MongoDB\Client, que define el por defecto para todas las operaciones a menos que se sobrescriba
MongoDB\Database
MongoDB\Collection

Esta lista también indica el orden creciente de prioridad de las configuraciones de opciones. Por ejemplo, si configuras un typeMap para una colección, se anulará el tipo de mapeo configurado en la base de datos.

La librería PHP utiliza el siguiente mapa de tipos por defecto:

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

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

Arreglos a MongoDB\Model\BSONArray objetos
Documentos BSON embebidos y de nivel superior a objetos MongoDB\Model\BSONDocument

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

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 ordena a la librería de 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 opción typeMap. La interfaz Persistable es análoga a la interfaz Serializable.de PHP.

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

Ejemplo

Considera la siguiente definición de clase Person, que implementa la interfaz Persistable y especifica cómo serializar y deserializar campos de objetos 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 librería PHP agrega automáticamente el campo __pclass para rastrear el nombre de la clase correspondiente del documento, lo que permite deserializar el documento en un objeto Person.

Nota

Puedes usar la interfaz Persistable solo para documentos BSON raíz e incrustados, no para arreglos 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 los enums respaldados, consulta Enums respaldados 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 a 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 lee 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 librerías PHP discutidos en esta guía, consulta la siguiente documentación de la API de la librería:

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

Volver

Decimal128

Time Series