BSON 데이터로 작업하기

개요

이 가이드 에서는 PHP 라이브러리를 사용하여 BSON 문서를 만들고 상호 작용 방법을 학습 수 있습니다.

BSON 또는 바이너리 JSON 은 MongoDB 데이터를 구성하고 저장 데 사용하는 데이터 형식입니다. 이 데이터 형식은 모든 JSON 데이터 구조 유형을 포함하며 날짜, 다른 크기의 정수, ObjectId 값 및 바이너리 데이터를 포함한 다른 유형도 지원합니다. PHP 라이브러리는 BSON 데이터를MongoDB\Model\BSONArray MongoDB\Model\BSONDocument 저장 위해 및 유형을 제공합니다.

팁

지원되는 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 문서 변경

PHP 에서 연관 배열 수정하는 데 사용하는 것과 동일한 표기법을 사용하여 BSON 문서 의 내용을 수정할 수 있습니다. 이 예시 샘플 BSON 문서:를 다음과 같이 변경합니다.

값이 12345인 새 restaurant_id 필드 추가합니다.
name 필드 값을 "Galaxy Pizza"(으)로 변경합니다.

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

참고

앞의 코드는 샘플 BSON 문서 의 인메모리 값만 변경합니다. MongoDB 에 저장된 값을 변경하는 데이터베이스 작업은 실행 하지 않습니다. MongoDB 에 저장된 문서를 수정하는 방법을 학습 문서 업데이트 가이드 참조하세요.

BSON 직렬화 사용자 지정

다음 섹션에서는 애플리케이션 BSON 데이터를 직렬화하는 방식을 구성하는 방법을 설명합니다.

유형 맵: typeMap 옵션을 사용하여 PHP 유형과 BSON 유형 간의 기본값 변환을 지정합니다.
지속 가능한 클래스: MongoDB\BSON\Persistable 인터페이스를 사용하여 직렬화를 활성화 .
열거형 값: bsonSerialize() 및 bsonUnserialize() 메서드를 사용하여 지원되는 열거형과 BSON 값 간의 직렬화를 지정합니다.

유형 맵

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 객체에 대한 배열
MongoDB\Model\BSONDocument 객체에 대한 최상위 및 포함된 BSON 문서

유형 맵은 MongoDB\ BSON\Unserializable 인터페이스를 구현하는 모든 클래스를 지정할 수 있습니다.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 인터페이스를 구현 클래스를 만들 수 있습니다. 이 인터페이스는 typeMap 옵션 없이 PHP 확장 프로그램의 지속성 사양에 따라 직렬화 및 역직렬화를 자동으로 수행하도록 PHP 라이브러리에 지시합니다.Persistable 인터페이스는 PHP의 직렬화 가능 인터페이스와 유사합니다.

BSON 에서 PHP 변수를 역직렬화할 때 Persistable 객체 의 인코딩된 클래스 이름이 typeMap 옵션에 지정된 모든 클래스를 재정의합니다. 그러나 array, stdClass 또는 object 유형은 재정의하지 않습니다.

예시

Persistable 인터페이스를 구현하고 객체 필드를 BSON 값으로 직렬화 및 역직렬화하는 방법을 지정하는 다음 Person 클래스 정의를 고려하세요.

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 객체 로 역직렬화할 수 있습니다.

참고

루트 및 내장된 BSON 문서에만 Persistable 인터페이스를 사용할 수 있으며, BSON 배열은 사용할 수 없습니다.

Enum Values

백업된 열거형을 BSON 데이터로 직렬화 및 역직렬화할 수 있습니다. 지원되는 열거형 값은 케이스 값으로 직렬화되지만 케이스 값이 없는 순수 열거형은 직접 직렬화할 수 없습니다. 이러한 변환을 수행하려면 클래스 정의에서 bsonSerialize() 및 bsonUnserialize() 메서드를 정의하여 직렬화 로직을 지정해야 합니다.

팁

지원되는 열거형에 대해 자세히 학습 PHP 확장 문서에서 지원되는 열거형을 참조하세요.

예시

두 개의 정수 값 케이스가 있는 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

시계열