레거시 드라이버 업그레이드 가이드

이 페이지의 내용

개요

BSON
유형 클래스
레거시 드라이버 에뮬레이션
collection API
삽입된 문서의 ID에 액세스
대량 쓰기 작업
MongoCollection::save() 제거됨
그룹 명령 도우미

개요

MongoDB PHP 라이브러리 및 기본 mongodb 확장 레거시 확장과의 API 차이점이 mongo 있습니다. 이 페이지에서는 레거시 드라이버에서 업그레이드하는 사용자를 위해 이러한 차이점을 요약하여 설명합니다.

또한 커뮤니티에서 개발한 mongo-php-adapter 라이브러리가 존재하며, 이는 mongo 이 라이브러리와 확장을 사용하여 확장 API를 mongodb 구현합니다. 이 어댑터 라이브러리는 MongoDB에서 공식적으로 지원하지 않지만 언급해야 합니다.

BSON

유형 클래스

레거시 드라이버에서 업그레이드할 때 MongoId와 같은 유형 클래스는 MongoDB\BSON 네임스페이스 의 클래스로 바꿔야 합니다. . 새 드라이버는 또한 BSON types 에 대한 인터페이스를 도입하며, 이는 애플리케이션이 BSON 값에 대해 유형 힌트를 입력해야 하는 경우 선호되어야 합니다.

다음 표에는 새 드라이버의 동등한 클래스와 함께 모든 레거시 클래스가 나열되어 있습니다.

레거시 클래스	BSON type 클래스	BSON type 인터페이스
몽고이드	MongoDB\BSON\ObjectId	MongoDB\BSON\ObjectIdInterface
MongoCode	MongoDB\BSON\Javascript	MongoDB\BSON\JavascriptInterface
MongoDate	MongoDB\BSON\UTCDateTime	MongoDB\BSON\UTCDateTimeInterface
MongoRegex	MongoDB\BSON\Regex	MongoDB\BSON\RegexInterface
MongoBinData	MongoDB\BSON\Binary	MongoDB\BSON\BinaryInterface
MongoInt32	구현되지 않았습니다. [1]
MongoInt64	MongoDB\BSON\Int64	구현되지 않았습니다. [2]
MongoDBRef	구현되지 않았습니다. [3]
MongoMinKey	MongoDB\BSON\MinKey	MongoDB\BSON\MinKeyInterface
MongoMaxKey	MongoDB\BSON\MaxKey	MongoDB\BSON\MaxKeyInterface
MongoTimestamp	MongoDB\BSON\Timestamp	MongoDB\BSON\TimestampInterface

[1]	새 드라이버는 MongoInt32에 해당하는 클래스를 구현하지 않습니다. BSON을 디코딩할 때 32비트 정수는 항상 PHP 정수로 표시됩니다. BSON을 인코딩할 때, PHP 정수는 해당 값에 따라 32비트 또는 64비트 정수로 인코딩됩니다.

[2]	MongoDB\BSON\Int64 에는 인터페이스가 정의되어 있지 않습니다.

[3]	(1, 2, 3) DBRef는 적절한 BSON 유형이 아니라 특정 구조를 가진 BSON 문서일 뿐이므로 새 드라이버는 MongoDBRef 에 해당하는 클래스를 구현하지 않습니다. 또한 새 드라이버는 DBRef 객체 작업을 위한 헬퍼를 제공하지 않는데, 이는 DBRef 객체의 사용이 권장되지 않기 때문입니다.

레거시 드라이버 에뮬레이션

레거시 mongo 확장 프로그램은 BSON 문서와 배열을 모두 PHP 배열로 반환했습니다. PHP 배열은 작업하기 편리하지만, 이 동작은 문제가 있었습니다:

서로 다른 BSON types이 동일한 PHP으로 역직렬화할 수 있습니다(예: {"0": "foo"} 및 ["foo"])로 인해 원래 BSON 유형을 추론하는 것이 불가능했습니다.
숫자로 인덱스된 PHP 배열은 키 시퀀스에 공백이 있는 경우 BSON 문서로 직렬화됩니다. 이러한 격차는 요소를 제거하기 위해 키 설정을 해제하고 배열을 숫자로 다시 인덱스하는 것을 잊기 때문에 발생합니다.

MongoDB PHP 라이브러리의 BSONDocument 및 BSONArray 클래스는 직렬화 및 역직렬화 중에 BSON 유형 정보를 보존하여 이러한 문제를 해결합니다. 그러나 일부 사용자는 여전히 레거시 동작을 선호할 수 있습니다. 원하는 경우 typeMap 옵션을 사용하여 라이브러리가 모든 것을 PHP 배열로 반환하도록 할 수 있습니다.

<?php
$client = new MongoDB\Client(
    'mongodb://127.0.0.1/',
    [],
    [
        'typeMap' => [
            'array' => 'array',
            'document' => 'array',
            'root' => 'array',
        ],
    ]
);
$document = $client->test->zips->findOne(['_id' => '94301']);
var_dump($document);

위 예제에서는 다음과 유사한 내용이 출력됩니다.

array(5) {
  ["_id"]=>
  string(5) "94301"
  ["city"]=>
  string(9) "PALO ALTO"
  ["loc"]=>
  array(2) {
    [0]=>
    float(-122.149685)
    [1]=>
    float(37.444324)
  }
  ["pop"]=>
  int(15965)
  ["state"]=>
  string(2) "CA"
}

collection API

이 라이브러리의 MongoDB\Collection 클래스는 MongoDB의 크로스 드라이버 CRUD 를 구현합니다. 및 인덱스 관리 사양. 새 사양에 따라 일부 메서드 이름이 변경되었지만, 새 클래스는 몇 가지 주목할 만한 예외를 제외하고 레거시 드라이버의 MongoCollection 클래스와 동일한 기능을 제공합니다.

새 API를 설계할 때 지침 원칙은 이전 API에 사용된 오버로드된 용어보다 명시적인 메서드 이름을 사용하는 것이 좋습니다. 예를 들어 MongoCollection::save() 와 MongoCollection::findAndModify() 는 인수에 따라 작동 모드가 다릅니다. 또한 특정 필드 업데이트 와 전체 문서 교체를 구분하기 위해 메서드가 분할되었습니다.

다음 표에는 새 드라이버의 모든 레거시 메서드와 이에 상응하는 메서드가 나열되어 있습니다.

MongoCollection 메서드	`MongoDB\Collection` 메서드
`MongoCollection::aggregate()`	`MongoDB\Collection::aggregate()`
`MongoCollection::aggregateCursor()`	`MongoDB\Collection::aggregate()`
`MongoCollection::batchInsert()`	`MongoDB\Collection::insertMany()`
`MongoCollection::count()`	`MongoDB\Collection::count()`
`MongoCollection::createDBRef()`	아직 구현되지 않았습니다. [3]
`MongoCollection::createIndex()`	`MongoDB\Collection::createIndex()`
`MongoCollection::deleteIndex()`	`MongoDB\Collection::dropIndex()`
`MongoCollection::deleteIndexes()`	`MongoDB\Collection::dropIndexes()`
`MongoCollection::drop()`	`MongoDB\Collection::drop()`
`MongoCollection::distinct()`	`MongoDB\Collection::distinct()`
`MongoCollection::ensureIndex()`	`MongoDB\Collection::createIndex()`
`MongoCollection::find()`	`MongoDB\Collection::find()`
`MongoCollection::findAndModify()`	`MongoDB\Collection::findOneAndDelete()`, `MongoDB\Collection::findOneAndReplace()` 및 `MongoDB\Collection::findOneAndUpdate()`
`MongoCollection::findOne()`	`MongoDB\Collection::findOne()`
`MongoCollection::getDBRef()`	구현되지 않았습니다. [3]
`MongoCollection::getIndexInfo()`	`MongoDB\Collection::listIndexes()`
`MongoCollection::getName()`	`MongoDB\Collection::getCollectionName()`
`MongoCollection::getReadPreference()`	`MongoDB\Collection::getReadPreference()`
`MongoCollection::getSlaveOkay()`	구현되지 않았습니다.
`MongoCollection::getWriteConcern()`	`MongoDB\Collection::getWriteConcern()`
`MongoCollection::group()`	구현되지 않았습니다. `MongoDB\Database::command()` 을(를) 사용합니다. 예제는 그룹 명령 도우미 를 참조하세요.
`MongoCollection::insert()`	`MongoDB\Collection::insertOne()`
`MongoCollection::parallelCollectionScan()`	구현되지 않았습니다.
`MongoCollection::remove()`	`MongoDB\Collection::deleteMany()` 개인정보 정책에 `MongoDB\Collection::deleteOne()`
`MongoCollection::save()`	`MongoDB\Collection::insertOne()` 또는 `MongoDB\Collection::replaceOne()` 를 `upsert` 옵션으로 바꿉니다.
`MongoCollection::setReadPreference()`	구현되지 않았습니다. `MongoDB\Collection::withOptions()` 을(를) 사용합니다.
`MongoCollection::setSlaveOkay()`	구현되지 않았습니다.
`MongoCollection::setWriteConcern()`	구현되지 않았습니다. `MongoDB\Collection::withOptions()` 을(를) 사용합니다.
`MongoCollection::update()`	`MongoDB\Collection::replaceOne()`, `MongoDB\Collection::updateMany()` 및 `MongoDB\Collection::updateOne()`.
`MongoCollection::validate()`	구현되지 않았습니다.

삽입된 문서의 ID에 액세스

레거시 드라이버에서 , 및 (삽입 시) 는MongoCollection::insert() 생성된MongoCollection::batchInsert() MongoCollection::save() _id ObjectId(즉, MongoId 객체)가 있는 키를 삽입하여 입력 인수를 수정합니다. 이 동작은 참조로 전달되는 인수에 의존하지 않기 때문에 약간의 해킹이었습니다. ; 대신 확장 API를 통해 메모리를 직접 수정했으며 PHP 사용자 영역에서는 구현할 수 없었습니다. 따라서 새 드라이버에서는 더 이상 수행되지 않습니다.

삽입된 문서의 ID(생성 여부와 관계없이)는 쓰기 결과 객체에서 다음 메서드를 통해 액세스할 수 있습니다.

MongoDB\InsertOneResult::getInsertedId() 다음의 경우: MongoDB\Collection::insertOne()
MongoDB\InsertManyResult::getInsertedIds() 다음의 경우: MongoDB\Collection::insertMany()
MongoDB\BulkWriteResult::getInsertedIds() 다음의 경우: MongoDB\Collection::bulkWrite()

대량 쓰기 작업

레거시 드라이버의 MongoWriteBatch 클래스가 범용 MongoDB\Collection::bulkWrite() 메서드로 대체되었습니다. 레거시 드라이버는 동일한 유형의 대량 작업만 허용했지만, 새로운 방법은 작업을 혼합하여 수행할 수 있습니다(예: 삽입, 업데이트 및 삭제).

MongoCollection::save() 제거됨

MongoCollection::save()삽입 또는 업서트 작업에 필요한 구문이던 이 제거되어 명시적으로 MongoDB\Collection::insertOne() 또는 MongoDB\Collection::replaceOne() ( upsert 옵션 포함)를 사용할 수 있게 되었습니다.

save 메서드는 과 같은 대화형 환경에서 사용되지만 MongoDB shell 의도적으로 CRUD 사양 에서 제외되었습니다. 언어 드라이버의 경우. 일반적으로 애플리케이션 코드는 문서에 식별자가 있는지 알고 있어야 하며, 문서를 명시적으로 삽입하거나 대체하고 반환된 MongoDB\InsertOneResult 또는 MongoDB\UpdateResult 을 각각 처리할 수 있어야 합니다. 이렇게 하면 부주의하고 잠재적으로 위험한 전체 문서 교체를 방지하는 데에도 도움이 됩니다.

그룹 명령 도우미

MongoDB\Collection 에는 그룹 명령에 대한 헬퍼 메서드가 없습니다. 다음 예제에서는 MongoDB\Database::command() 메서드를 사용하여 그룹 명령을 실행하는 방법을 보여 줍니다.

<?php
$database = (new MongoDB\Client)->selectDatabase('db_name');
$cursor = $database->command([
    'group' => [
        'ns' => 'collection_name',
        'key' => ['field_name' => 1],
        'initial' => ['total' => 0],
        '$reduce' => new MongoDB\BSON\Javascript('...'),
    ],
]);
$resultDocument = $cursor->toArray()[0];

돌아가기

Stable API

API 문서