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 Transforme seus dados com 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 documents
foreach ($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 documents
echo '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 documents
echo '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 alterações de dados.

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 specifications
for ($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.