/ /

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 librería PHP proporciona el MongoDB\Model\BSONArray y MongoDB\Model\BSONDocument tipos para almacenar datos BSON.

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 cambia únicamente los valores en memoria del documento BSON de muestra. No ejecuta ninguna operación de base de datos que cambie los valores almacenados en MongoDB. Para aprender cómo modificar documentos almacenados en MongoDB, consulta 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 tipo: Utilice la opción typeMap para especificar la conversión por defecto entre los tipos de PHP y los BSON types.
Clases persistentes: Utilice la interfaz MongoDB\BSON\Persistable 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 type map puede especificar cualquier clase que implemente el MongoDB\BSON\Unserializable interfaz. También puede especificar conversiones de los tipos array, stdClass y object.

Ejemplo de Mapa de Tipos Personalizado

El siguiente ejemplo establece la opción typeMap para la colección restaurants que serializa arreglos 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

Puedes serializar y deserializar enumeraciones respaldadas en datos BSON. Los valores de enums respaldados se serializan como su valor de caso, mientras que los enums puros sin valores de caso no se pueden serializar directamente. Para realizar estas conversiones, debes especificar la lógica de serialización definiendo los métodos bsonSerialize() y bsonUnserialize() en la definición de tu 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

Los enumerados no pueden implementar las interfaces MongoDB\BSON\Unserializable y MongoDB\BSON\Persistable porque los casos de enumerado no tienen estado y no pueden ser instanciados como objetos de clase. Sin embargo, los enumerados puros y respaldados pueden implementar MongoDB\BSON\Serializable, que puedes usar para anular el comportamiento por defecto de serialización de enumerados.

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