MongoDB\BSON\Serializable::bsonSerialize

Provides an array or document to serialize as BSON

説明

abstract public arraystdClassMongoDB\BSON\DocumentMongoDB\BSON\PackedArray MongoDB\BSON\Serializable::bsonSerialize()

Called during serialization of the object to BSON. The method must return an array, stdClass, MongoDB\BSON\Document, or MongoDB\BSON\PackedArray.

Root documents (e.g. a MongoDB\BSON\Serializable passed to MongoDB\BSON\fromPHP) will always be serialized as a BSON document. For field values, associative arrays and stdClass instances will be serialized as a BSON document and sequential arrays (i.e. sequential, numeric indexes starting at 0) will be serialized as a BSON array.

Users are encouraged to include an _id property (e.g. a MongoDB\BSON\ObjectId initialized in your constructor) when returning data for a BSON root document; otherwise, the driver or database will need to generate a MongoDB\BSON\ObjectId when inserting or upserting the document, respectively.

パラメータ

この関数にはパラメータはありません。

戻り値

An array, stdClass, MongoDB\BSON\Document, or MongoDB\BSON\PackedArray to be serialized as a BSON array or document.

変更履歴

バージョン

説明

PECL mongodb 1.17.0

The return type was changed from arrayobject. Instead of object, the return type now specifies stdClass. Classes that implement this interface must be changed to no longer declare an object return type. As the return type is tentative, a deprecation warning is emitted on PHP 8.1 and newer.

In addition to the changes above, the driver now also supports returning instances of MongoDB\BSON\Document and MongoDB\BSON\PackedArray. Please note that any MongoDB\BSON\PackedArray instances returned are silently converted to objects when stored as root documents. They are stored as arrays when used as an embedded field value.

例

例1 MongoDB\BSON\Serializable::bsonSerialize returning an associative array for root document


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

$bson = MongoDB\BSON\fromPHP(new MyDocument);
echo MongoDB\BSON\toJSON($bson), "\n";

?>

上の例の出力は、たとえば以下のようになります。

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

例2 MongoDB\BSON\Serializable::bsonSerialize returning a sequential array for root document


<?php

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

$bson = MongoDB\BSON\fromPHP(new MyArray);
echo MongoDB\BSON\toJSON($bson), "\n";

?>

上の例の出力は以下となります。

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

例3 MongoDB\BSON\Serializable::bsonSerialize returning an associative array for document field


<?php

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

$value = ['document' => new MyDocument];
$bson = MongoDB\BSON\fromPHP($value);
echo MongoDB\BSON\toJSON($bson), "\n";

?>

上の例の出力は以下となります。

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

例4 MongoDB\BSON\Serializable::bsonSerialize returning a sequential array for document field


<?php

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

$value = ['array' => new MyArray];
$bson = MongoDB\BSON\fromPHP($value);
echo MongoDB\BSON\toJSON($bson), "\n";

?>

上の例の出力は以下となります。

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

参考

MongoDB\BSON\Unserializable::bsonUnserialize
MongoDB\BSON\Persistable
Persisting Data