Provides an array or document to serialize as BSON

# MongoDB\BSON\Serializable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON

### 说明

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

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\Document::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 the constructor) when returning data for a BSON root document. In the absence of an _id property, the extension or server will generate a MongoDB\BSON\ObjectId for insert or upsert operations, respectively.

### 参数

此函数没有参数。

### 返回值

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

### 更新日志

版本 | 说明
--- | ---
PECL mongodb 2.0.0 | 之前声明为暂定的返回类型现在已被强制执行。
PECL mongodb 1.17.0 | The return type was changed from array|object. 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 extension 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'];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyDocument)->toRelaxedExtendedJSON(), "\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];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyArray)->toRelaxedExtendedJSON(), "\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];

    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\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];

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

    ?>

以上示例会输出：

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

### 参见

- MongoDB\BSON\Unserializable::bsonUnserialize() - Constructs the object from a BSON array or document
- MongoDB\BSON\Persistable
- Persisting Data

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open