Operações com construtores

Visão geral

Neste guia, você aprenderá sobre as classes de construtor que a biblioteca PHP fornece para criar os tipos usados em suas operações. Você pode usar as classes de construtor e os métodos de fábrica do recurso Construtor de Agregações para criar filtros para outras operações, como operações de localização, atualização e exclusão. Para saber mais sobre o Construtor de Agregações, consulte a seção Construtor de Agregações do guia Agregação.

Usar construtores para criar queries ajuda a identificar erros no tempo de compilação e evitá-los no tempo de execução. Este guia fornece informações sobre classes de construtores que você pode usar para executar as seguintes tarefas:

• Criar um filtro

• Definir um documento de atualização

• Modificar o resultado do change stream

$options = [    'limit' => 5,    '<option name>' => '<specification>',];

Este guia fornece exemplos de como usar construtores em operações não de agregação. Para visualizar exemplos de agregação, consulte o guia Operações de agregação.

$collection = $client->sample_geospatial->shipwrecks;

Importar classes de construtor

Para executar os exemplos deste guia, você deve importar as seguintes classes para seu aplicação:

use MongoDB\Builder\Pipeline;use MongoDB\Builder\Query;use MongoDB\Builder\Stage;

Criar um filtro

Você pode utilizar métodos de fábrica da classe de construtor Query para criar definições de filtro para utilizar em localizar, atualizar e excluir operações. Ao usar o método de fábrica Query::query() para criar queries, você pode usar a sintaxe de argumentos nomeados e implementar a segurança de tipos. Para saber mais sobre como criar filtros, consulte o guia Especificar uma consulta.

As etapas a seguir descrevem como criar uma definição de filtro usando construtores:

1. Chame o método Query::query() para criar uma query.

2. Passe o nome do campo para filtrar e um método de fábrica da classe Query. Você pode passar um ou mais pares de nomes de campo e critérios no filtro para aplicar várias cláusulas.

O código a seguir mostra o modelo para criar uma definição de filtro usando construtores:

$filter = Query::query(    <field name>: Query::<factory method>(<parameters>),    <field name>: Query::<factory method>(<parameters>),    ...);

Para combinar critérios de query usando operadores de query lógica ($and, $or, $not, $nor), você pode usar o seguinte modelo de query:

$filter = Query::<logical operator>(    Query::query(<field name>: Query::<factory method>(<parameters>)),    Query::query(<field name>: Query::<factory method>(<parameters>)),    ...);

Para saber mais, consulte Operadores de query lógica no manual do MongoDB Server.

As seções a seguir fornecem exemplos que usam construtores para criar definições de filtro para diferentes operações.

// Creates a query filter by using builders and// retrieves matching documents$docs = $collection->find(    Query::query(        feature_type: Query::eq('Wrecks - Visible'),        coordinates: Query::near(            Query::geometry(                type: 'Point',                coordinates: [-79.9, 9.3],            ),            maxDistance: 10000,        ),    ),);
// Prints matching documentsforeach ($docs as $doc) {    echo json_encode($doc), PHP_EOL;}

{"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9137115,9.3390503],...}{"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9357223,9.3340302],...}{"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9081268,9.3547792],...}// Results truncated

// Creates a query filter by using builders// and deletes the first matching document$result = $collection->deleteOne(    Query::or(        Query::query(feature_type: Query::regex('nondangerous$', '')),        Query::query(depth: Query::gt(10.0)),    ),);
// Prints number of deleted documentsecho 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;

Deleted documents: 1

Definir um documento de atualização

Você pode utilizar métodos de fábrica da classe de construtor Stage para criar documentos de atualização. Atualizar documentos descreve as atualizações a serem feitas nos documentos de destino. Para saber mais sobre como atualizar documentos, consulte o guia Atualizar documentos.

As etapas a seguir descrevem como criar um documento de atualização usando construtores:

1. Crie uma instância Pipeline .

2. Passe um ou mais estágios chamando métodos da classe Stage, como Stage::set(), e passando nomes e valores de campo .

O código a seguir mostra o modelo para definir uma atualização usando construtores:

$update = new Pipeline(    Stage::set(<field name>: <value>),    Stage::set(<field name>: <value>),    ...);

Este exemplo executa as seguintes ações:

• Usa o método de fábrica Query::eq() para corresponder a documentos nos quais o valor de campo watlev é 'partly submerged at high water'

• Utiliza o método Stage::set() para definir o campo year como 1870

• Chama o método MongoDB\Collection::updateOne() para executar a atualização

• Imprime o número de documentos atualizados

// Creates a query filter and an update document by// using builders and updates the first matching document$result = $collection->updateOne(    Query::query(watlev: Query::eq('partly submerged at high water')),    new Pipeline(        Stage::set(year: 1870),    ),);
// Prints number of updated documentsecho 'Updated documents: ', $result->getModifiedCount(), PHP_EOL;

Updated documents: 1

Modificar o resultado do change stream

Você pode usar métodos de fábrica da classe Stage para modificar a saída de um fluxo de alteração criando um pipeline. Para saber mais sobre change streams, consulte o guia Monitorar dados com change streams.

As etapas a seguir descrevem como criar um filtro de fluxo de alteração usando construtores:

1. Crie uma matriz.

2. Passe um ou mais $match estágios chamando os métodos de fábrica da classe Stage e os parâmetros exigidos.

O código a seguir mostra o modelo para modificar a saída do change stream usando construtores:

$pipeline = [    Stage::<factory method>(...),    Stage::<factory method>(...),    ...];

Você pode passar esse pipeline para os seguintes métodos:

• MongoDB\Client::watch()

• MongoDB\Database::watch()

• MongoDB\Collection::watch()

Este exemplo executa as seguintes ações:

• Usa o método Stage::match() para filtrar apenas eventos de alteração para operações de atualização

• Utiliza o método Stage::project() para produzir apenas os campos operationType, ns (namespace) e fullDocument

• Chama o método MongoDB\Collection::watch() para abrir o fluxo de alterações e define a opção fullDocument para gerar o documento completo após a atualização

• Impressões alteram eventos à medida que eles ocorrem

// Creates a pipeline to filter for update operations and return// only specific fields$pipeline = [    Stage::match(operationType: Query::eq('update')),    Stage::project(operationType: 1, ns: 1, fullDocument: 1),];
// Opens the change stream$changeStream = $collection->watch(    $pipeline,    ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP],);
// Prints change events based on the pipeline specificationsfor ($changeStream->rewind(); true; $changeStream->next()) {    if (! $changeStream->valid()) {        continue;    }    $event = $changeStream->current();    echo json_encode($event), PHP_EOL;
    if ($event['operationType'] === 'invalidate') {        break;    }}

{  "_id":...,  "operationType":"update",  "fullDocument":{"_id":...,"feature_type":"Wrecks - Visible",...},  "ns":{"db":"sample_geospatial","coll":"shipwrecks"}}

Para saber mais sobre as informações fornecidas por eventos de alteração, consulte Eventos de alteração no manual do MongoDB Server.