MongoDB\BSON\Serializable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Serializable::bsonSerialize — Proporciona un array o documento para serializar como BSON

Descripción

abstract public MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray

Se invoca durante la serialización del objeto a BSON. El método debe devolver un array, stdClass, MongoDB\BSON\Document, o MongoDB\BSON\PackedArray.

Los documentos raíz (por ejemplo, un MongoDB\BSON\Serializable pasado a MongoDB\BSON\Document::fromPHP()) siempre se serializarán como un documento BSON. Para los valores de campo, los arrays asociativos y las instancias de stdClass se serializarán como un documento BSON y los arrays secuenciales (es decir, índices numéricos secuenciales que comienzan en 0) se serializarán como un array BSON.

Se recomienda a los usuarios incluir una propiedad _id (por ejemplo, un MongoDB\BSON\ObjectId inicializado en el constructor) al devolver datos para un documento raíz BSON. En ausencia de una propiedad _id, la extensión o el servidor generará un MongoDB\BSON\ObjectId para operaciones de inserción o actualización (upsert), respectivamente.

Parámetros

Esta función no contiene ningún parámetro.

Valores devueltos

Un array, stdClass, MongoDB\BSON\Document, o MongoDB\BSON\PackedArray que se serializará como un array o documento BSON.

Historial de cambios

Versión	Descripción
PECL mongodb 2.0.0	Los tipos de retorno previamente declarados como provisionales ahora son aplicados.
PECL mongodb 1.17.0	El tipo de retorno se cambió de array\|object. En lugar de object, el tipo de retorno ahora especifica stdClass. Las clases que implementan esta interfaz deben modificarse para dejar de declarar un tipo de retorno object. Como el tipo de retorno es tentativo, se emite una advertencia de obsolescencia en PHP 8.1 y versiones posteriores. Además de los cambios anteriores, la extensión ahora también admite devolver instancias de MongoDB\BSON\Document y MongoDB\BSON\PackedArray. Tenga en cuenta que cualquier instancia de MongoDB\BSON\PackedArray devuelta se convierte silenciosamente en objetos cuando se almacenan como documentos raíz. Se almacenan como arrays cuando se utilizan como valor de campo incrustado.

Versión

Descripción

PECL mongodb 2.0.0

Los tipos de retorno previamente declarados como provisionales ahora son aplicados.

PECL mongodb 1.17.0

El tipo de retorno se cambió de array|object. En lugar de object, el tipo de retorno ahora especifica stdClass. Las clases que implementan esta interfaz deben modificarse para dejar de declarar un tipo de retorno object. Como el tipo de retorno es tentativo, se emite una advertencia de obsolescencia en PHP 8.1 y versiones posteriores. Además de los cambios anteriores, la extensión ahora también admite devolver instancias de MongoDB\BSON\Document y MongoDB\BSON\PackedArray. Tenga en cuenta que cualquier instancia de MongoDB\BSON\PackedArray devuelta se convierte silenciosamente en objetos cuando se almacenan como documentos raíz. Se almacenan como arrays cuando se utilizan como valor de campo incrustado.

Ejemplos

Ejemplo #1 MongoDB\BSON\Serializable::bsonSerialize() que devuelve un array asociativo para documento raíz

<?php

class MyDocument implements MongoDB\BSON\Serializable
{
    private $id;

    function __construct()
    {
        $this->id = new MongoDB\BSON\ObjectId;
    }

    function bsonSerialize(): array
    {
        return ['_id' => $this->id, 'foo' => 'bar'];
    }
}

echo MongoDB\BSON\Document::fromPHP(new MyDocument)->toRelaxedExtendedJSON(), "\n";

?>

Resultado del ejemplo anterior es similar a:

{ "_id" : { "$oid" : "56cccdcada14d8755a58c591" }, "foo" : "bar" }

Ejemplo #2 MongoDB\BSON\Serializable::bsonSerialize() que devuelve un array secuencial para documento raíz

<?php

class MyArray implements MongoDB\BSON\Serializable
{
    function bsonSerialize(): array
    {
        return [1, 2, 3];
    }
}

echo MongoDB\BSON\Document::fromPHP(new MyArray)->toRelaxedExtendedJSON(), "\n";

?>

El ejemplo anterior mostrará:

{ "0" : 1, "1" : 2, "2" : 3 }

Ejemplo #3 MongoDB\BSON\Serializable::bsonSerialize() que devuelve un array asociativo para campo de documento

<?php

class MyDocument implements MongoDB\BSON\Serializable
{
    function bsonSerialize(): array
    {
        return ['foo' => 'bar'];
    }
}

$value = ['document' => new MyDocument];

echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

?>

El ejemplo anterior mostrará:

{ "document" : { "foo" : "bar" } }

Ejemplo #4 MongoDB\BSON\Serializable::bsonSerialize() que devuelve un array secuencial para campo de documento

<?php

class MyArray implements MongoDB\BSON\Serializable
{
    function bsonSerialize(): array
    {
        return [1, 2, 3];
    }
}

$value = ['array' => new MyArray];

echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

?>

El ejemplo anterior mostrará:

{ "array" : [ 1, 2, 3 ] }

Ver también

MongoDB\BSON\Unserializable::bsonUnserialize() - Construye el objeto a partir de un array o documento BSON
MongoDB\BSON\Persistable
Persistir datos