Guia de atualização de driver legado

Classes de tipo

Ao atualizar a partir do driver legado, classes de tipo como MongoId devem ser substituídas por classes no namespace MongoDB\BSON. O novo driver também apresenta interfaces para seus tipos de BSON, que devem ser preferidos se os aplicativos precisarem digitar dica em relação aos valores de BSON.

A tabela a seguir lista todas as classes de legado juntamente com a classe equivalente no novo driver.

Emulando o driver legado

A extensão legado de mongo retornou documento e arrays BSON como arrays PHP. Embora as arrays PHP sejam convenientes para trabalhar, esse comportamento era problemático:

• Diferentes BSON types podem desserializar para o mesmo valor PHP (por exemplo {"0": "foo"} e ["foo"]), o que tornou impossível inferir o tipo de BSON original.

• Arrays PHP indexadas numericamente seriam serializadas como documentos BSON se houver uma lacuna em sua sequência de chaves. Essas lacunas eram causadas por desconfigurar uma chave para remover um elemento e esquecer de reindexar numericamente a array.

As classes BSONDocument e BSONArray da biblioteca PHP do MongoDB abordam essas preocupações preservando as informações do tipo de BSON durante a serialização e a desserialização; no entanto, alguns usuários ainda podem preferir o comportamento legado. Se desejar, você pode usar a opção typeMap para que a biblioteca retorne tudo como uma array 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);

O exemplo acima produziria algo semelhante a:

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"
}

Acessando ID de documento inseridos

No driverMongoCollection::insert() legado, MongoCollection::batchInsert(), e MongoCollection::save() (ao inserir) modificariam seu argumento de entrada injetando uma _id chave com um ObjectId gerado (ou seja, objeto MongoId). Esse comportamento foi meio que um esquema, pois não dependia do argumento passado por referência; em vez disso, ele modificou diretamente a memória por meio da API de extensão e não pôde ser implementado no usuário do PHP. Dessa forma, isso não é mais feito no novo driver e na biblioteca.

As ID de documento inseridos (gerados ou não) podem ser acessadas por meio dos seguintes métodos nos objeto de resultado da gravação:

• MongoDB\InsertOneResult::getInsertedId() Para MongoDB\Collection::insertOne()

• MongoDB\InsertManyResult::getInsertedIds() Para MongoDB\Collection::insertMany()

• MongoDB\BulkWriteResult::getInsertedIds() Para MongoDB\Collection::bulkWrite()

Operações de gravação em massa

As classes MongoWriteBatch do driver legado foram substituídas por um método MongoDB\Collection::bulkWrite() de uso geral. Enquanto o driver legado só permitia operações em massa do mesmo tipo, o novo método permite que operações sejam mistas (por exemplo inserções, atualizações e exclusões).

MongoCollection::save() Removido

MongoCollection::save(), que era o açúcar sintático para uma operação de inserção ou upsert, foi removido em favor do uso explícito de MongoDB\Collection::insertOne() ou MongoDB\Collection::replaceOne() (com a opção upsert ).

Embora o save método tenha sua utilidade para ambientes interativos, como o shell do MongoDB, ele foi intencionalmente excluído da especificação CRUD para drivers de idioma. Geralmente, o código do aplicativo deve saber se o documento tem um identificador e ser capaz de inserir ou substituir explicitamente o documento e lidar com o MongoDB\InsertOneResult ou MongoDB\UpdateResult retornado, respectivamente. Isso também ajuda a evitar substituições inadvertidas e potencialmente perigosas de documentos completos.

Auxiliar de comando de grupo

MongoDB\Collection não tem um método auxiliar para o comando de grupo . O exemplo seguinte demonstra como executar um comando de grupo utilizando o método 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];