BSONデータとの連携

Overview

このガイドでは、 PHPライブラリを使用してBSONドキュメントの作成と操作の方法を学習できます。

BSON（Binary JSON）は、 MongoDB がデータを整理して保存するために使用するデータ形式です。このデータ形式には、すべてのJSONデータ構造タイプが含まれ、日付、異なるサイズの整数、ObjectId 値、バイナリデータなどの他のタイプもサポートしています。PHPライブラリには、MongoDB\Model\BSONArray BSONデータを保存するためのMongoDB\Model\BSONDocument およびタイプが用意されています。

Tip

サポートされているBSON types の完全なリストを表示するには、 MongoDB Serverマニュアルの BSON types を参照してください。

サンプルデータ

このガイドのコード例は、次のサンプルBSONドキュメントを参照。

{
    "address" : {
        "street" : "Pizza St",
        "zipcode" : "10003"
    },
    "coord" : [-73.982419, 41.579505]
    "cuisine" : "Pizza",
    "name" : "Planet Pizza"
}

BSON ドキュメントの作成

PHPで連想配列を作成するのと同じ表記を使用して、 BSONドキュメントを作成できます。PHPライブラリは、コレクションに挿入するときに、これらの値をBSONドキュメントに自動的に変換します。

次の例では、前述のサンプルBSONドキュメント:を表すBSONドキュメントを作成します。

$document = [
    'address' => [
        'street' => 'Pizza St',
        'zipcode' => '10003',
    ],
    'coord' => [-73.982419, 41.579505],
    'cuisine' => 'Pizza',
    'name' => 'Planet Pizza',
];

BSON ドキュメントの変更

BSONドキュメントの内容は、 PHPで連想配列を変更するのと同じ表記を使用して変更できます。この例では、サンプルBSONドキュメントに次の変更を加えます。

12345 の値を持つ新しい restaurant_idフィールドを追加します
nameフィールド値を "Galaxy Pizza" に変更

$document['restaurant_id'] = 12345;
$document['name'] = 'Galaxy Pizza';

注意

上記のコードは、サンプルBSONドキュメントのメモリ内の値のみを変更します。MongoDBに保存されている値を変更するデータベース操作は実行されません。MongoDBに保存されているドキュメントを変更する方法については、「ドキュメントの更新」ガイドを参照してください。

BSON直列化をカスタマイズ

次のセクションでは、アプリケーションがBSONデータを直列化する方法の構成方法について説明します。

タイプマップ : PHPタイプとBSONタイプ間のデフォルト変換を指定するには、typeMap オプションを使用します。
永続的なクラス :直列化を有効にするには、 MongoDB\BSON\Persistable インターフェースを使用します。
列挙値 : バックアップ列挙とBSON値間の直列化を指定するには、bsonSerialize() メソッドと bsonUnserialize() メソッドを使用します。

タイプマップ

PHPとBSON値間の直列化と逆直列化を構成する typeMap オプションは、次のレベルで設定できます。

MongoDB\Client、オーバーライドされない限り、すべての操作にデフォルトを設定します。
MongoDB\Database
MongoDB\Collection

このリストは、オプション設定の優先順位の増加順も示しています。例、コレクションに typeMap を設定すると、データベースに設定されたタイプマップが上書きされます。

PHPライブラリは、デフォルトで次の型のマップを使用します。

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

このタイプのマップは、両方の方向で次の変換を実行します。

配列からMongoDB\Model\BSONArrayオブジェクトへ
トップレベルと埋め込みBSONドキュメントからMongoDB\Model\BSONDocumentオブジェクトへ

型マップには、 MongoDB\ BSON \Unserialize インターフェースを実装する任意のクラスを指定できます。また、array stdClass、、object 型の変換を指定することもできます。

カスタムタイプマップの例

次の例では、配列とBSONドキュメントを MongoDB\Model\BSONDocument オブジェクトとして直列化する restaurantsコレクションの typeMap オプションを設定します。

$options = [
    'typeMap' => [
        'array' => 'MongoDB\Model\BSONDocument',
        'root' => 'MongoDB\Model\BSONDocument',
        'document' => 'MongoDB\Model\BSONDocument',
    ],
];
$db->createCollection('restaurants', $options);

永続的なクラス

MongoDB\ BSON \Persistable インターフェースを実装するクラスを作成できます。このインターフェースは、オプションを必要とせずに、 PHP拡張の永続性仕様に従って直列化と逆直列化を自動的に実行するようにPHPライブラリに指示します。 typeMapPersistableインターフェースは、PHP のシリアル化可能なインターフェースに類似しています。

PHP変数をBSONから逆直列化する場合、Persistableオブジェクトのエンコードされたクラス名は、typeMap オプションで指定されたすべてのクラスを上書きします。ただし、array、stdClass、または object のタイプは上書きされません。

例

次の Personクラス定義を検討してみましょう。これは Persistable インターフェースを実装し、オブジェクトフィールドを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'];
    }
}

次の例では、 Personオブジェクトを構築し、データベースに挿入し、同じタイプのオブジェクトとして読み取ります。

$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)
    }
}

返されたドキュメントは、次のBSONドキュメントと同等です。

{
  "_id" : ObjectId("56fad2c36118fd2e9820cfc1"),
  "__pclass" : BinData(128,"UGVyc29u"),
  "name" : "Bob",
  "createdAt" : ISODate("2016-03-29T19:08:51.218Z")
}

PHPライブラリは、ドキュメントに対応するクラス名を追跡するために __pclassフィールドを自動的に追加します。これにより、ドキュメントをPersonオブジェクトに逆シリアル化できます。

注意

Persistable インターフェースは、ルートBSONドキュメントと埋め込み BSON ドキュメントのみに使用でき、 BSON配列には使用できません。

Enum Values

バッキングされた列挙型をBSONデータにシリアル化および逆シリアル化できます。バックアップ列挙値はケース値としてシリアル化されますが、ケース値のない純粋な列挙値は直接シリアル化できません。これらの変換を実行するには、クラス定義で bsonSerialize() メソッドと bsonUnserialize() メソッドを定義し、直列化ロジックを指定する必要があります。

Tip

バックディングされた列挙型の詳細については、 PHP拡張ドキュメントの「バックアップされた列挙型」を参照してください。

例

整数値のケースが 2 つある Role という名前の次のバックアップ列挙を検討してみましょう。

enum Role: int
{
    case USER = 1;
    case ADMIN = 2;
}

この Userクラス定義には、Role列挙値を持つ roleフィールドが含まれており、そのフィールドを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']);
    }
}

次の例では、roleフィールドを含む Userオブジェクトを構築し、それをデータベースに挿入して、同じタイプのオブジェクトとして読み取ります。

$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) "..."
   }
}

注意

列挙型は、列挙のケースには状態がなく、クラスオブジェクトのようにインスタンス化できないため、MongoDB\BSON\Unserializable インターフェースと MongoDB\BSON\Persistable インターフェースを実装できません。ただし、単一列挙とバックアップ列挙では MongoDB\BSON\Serializable を実装できます。これを使用してデフォルトの列挙直列化動作をオーバーライドできます。

API ドキュメント

このガイドで説明されているPHPライブラリのメソッドやタイプの詳細については、次のライブラリAPIドキュメントを参照してください。

このガイドで説明するPHP拡張タイプの詳細については、次の拡張APIドキュメントを参照してください。

戻る

Decimal128

時系列