MongoDB\Client::watch()

Nesta página

Definição

Parâmetros
Return Values
Erros/exceções
Exemplos
Veja também

Novidade na versão 1.4.

Definição

MongoDB\Client::watch()

Executa uma operação dechange stream do no cliente. O change stream pode ser observado para alterações no nível do cluster.

function watch(
    array $pipeline = [],
    array $options = []
): MongoDB\ChangeStream

Parâmetros

$pipeline : array|object

O pipeline de estágios a ser anexado a um estágio $changeStream inicial.

$options : array

Uma array especificando as opções desejadas.

Nome	Tipo	Descrição
batchSize	inteiro	Especifica o tamanho do lote para o cursor, que se aplicará ao comando `aggregate` inicial e quaisquer comandos `getMore` subsequentes. Isso determina o número máximo de eventos de alteração para retornar em cada resposta do servidor. Independentemente da opção `batchSize`, a resposta inicial do comando `aggregate` para um change stream geralmente não inclui nenhum documento, a menos que outra opção seja usada para configurar seu ponto de partida (por exemplo `startAfter`).
Codec	MongoDB\Codec\DocumentCodec	Ocodec a ser usado para codificar ou decodificar documentos. Esta opção é mutuamente exclusiva com a opção `typeMap` . Novidade na versão 1.17.
agrupamento	array\|object	A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de string , como regras para letras maiúsculas e marcas de acento. Ao especificar agrupamento, o campo `locale` é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento.
comment	misto	Permite ao usuário especificar um comentário arbitrário para ajudar a rastrear a operação por meio do profiler de banco de dados, da saída currentOp e dos registros. O comentário pode ser qualquer tipo de BSON válido desde o MongoDB 4.4. As versões anteriores do servidor suportam apenas valores de string. Novidade na versão 1.13.
Documento completo	string	Determina como o campo de resposta `fullDocument` será preenchido para operações de atualização. Por padrão, os change stream retornam apenas o delta dos campo (por meio de um campo `updateDescription` ) para operações de atualização e `fullDocument` é omitido. As operações de inserção e substituição sempre incluem o campo `fullDocument` . As operações de exclusão omitem o campo, pois o documento não existe mais. Especifique "updateLookup" para retornar a versão atual do documento atualizado com o compromisso da maioria. O MongoDB 6.0+ permite retornar a pós-imagem do documento modificado se a collection tiver `changeStreamPreAndPostImages` habilitado. Especifique "whenAvailable" para retornar a pós-imagem, se disponível, ou um valor nulo, se não. Especifique "obrigatório" para retornar a pós-imagem, se disponível, ou gere um erro, se não. Os seguintes valores são aceitos: `MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP` `MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE` `MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED` Esta é uma opção do estágio do pipeline `$changeStream` .
fullDocumentBeforeChange	string	Determina como o campo de resposta `fullDocumentBeforeChange` será preenchido. Por padrão, o campo é omitido. O MongoDB 6.0+ permite retornar a pré-imagem do documento modificado se a collection tiver `changeStreamPreAndPostImages` habilitado. Especifique "whenAvailable" para retornar a pré-imagem, se disponível, ou um valor nulo, se não. Especifique "obrigatório" para retornar a pré-imagem, se disponível, ou gere um erro, se não. Os seguintes valores são aceitos: `MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE` `MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED` Esta é uma opção do estágio do pipeline `$changeStream` . Novidade na versão 1.13.
maxAwaitTimeMS	inteiro	Inteiro positivo que indica o limite de tempo em milissegundos para o servidor bloquear uma operação getMore se nenhum dado estiver disponível.
readConcern	MongoDB\Driver\ReadConcern	Preocupação de leitura a ser usada para a operação. O padrão é a preocupação de leitura do cliente.
readPreference	MongoDB\Driver\ReadPreference	Preferência de leitura a ser usada na operação. O padrão é a preferência de leitura do cliente. Isso é usado tanto para a agregação inicial do change stream quanto para a seleção do servidor durante uma retomada automática.
resumeAfter	array\|object	Especifica o ponto de partida lógico para o novo change stream. O campo `_id` em documentos retornados pelo change stream pode ser usado aqui. Usar essa opção em conjunto com `startAfter` e/ou `startAtOperationTime` resultará em um erro no servidor. As opções são mutuamente exclusivas. Esta é uma opção do estágio do pipeline `$changeStream` .
session	MongoDB\Driver\Session	Sessão do cliente a ser associada à operação.
showExpandedEvents	booleano	Se verdadeiro, instrui o servidor a incluir eventos DDL adicionais no change stream. Os eventos adicionais que podem ser incluídos são: `createIndexes` `dropIndexes` `modify` `create` `shardCollection` `reshardCollection` (servidor 6.1+) `refineCollectionShardKey` (servidor 6.1+) Isto não é suportado para versões de servidor anteriores à 6.0 e resultará em uma exceção no tempo de execução se utilizado. Esta é uma opção do estágio do pipeline `$changeStream` . Novidade na versão 1.13.
startAfter	array\|object	Especifica o ponto de partida lógico para o novo change stream. O campo `_id` em documentos retornados pelo change stream pode ser usado aqui. Ao contrário `resumeAfter`, essa opção pode ser usada com um token de retomada de um evento de "invalidação". Usar essa opção em conjunto com `resumeAfter` e/ou `startAtOperationTime` resultará em um erro no servidor. As opções são mutuamente exclusivas. Isto não é suportado para versões de servidor anteriores à 4.2 e resultará em uma exceção no tempo de execução se utilizado. Esta é uma opção do estágio do pipeline `$changeStream` . Novidade na versão 1.5.
startAtOperationTime	MongoDB\BSON\TimestampInterface	Se especificado, o change stream fornecerá apenas as alterações que ocorreram no ou após o registro de data/hora especificado. As respostas de comando de um servidor MongoDB 4.0+ incluem um `operationTime` que pode ser utilizado aqui. Por padrão, o `operationTime` retornado pelo comando `aggregate` inicial será utilizado se disponível. Usar essa opção em conjunto com `resumeAfter` e/ou `startAfter` resultará em um erro no servidor. As opções são mutuamente exclusivas. Isto não é suportado para versões de servidor anteriores à 4.0 e resultará em uma exceção no tempo de execução se utilizado. Esta é uma opção do estágio do pipeline `$changeStream` .
typeMap	array	O mapa de tipos aplicar aos cursores, o que determina como os documentos BSON são convertidos em valores PHP. O padrão é o mapa de tipos do cliente.

Return Values

Um objeto , que permite a iteração de MongoDB\ChangeStream eventos no fluxo de alterações por meio do Iterador interface.

Erros/exceções

MongoDB\Exception\UnexpectedValueException se a resposta do comando do servidor estiver malformada.

MongoDB\Exception\UnsupportedException se as opções forem usadas e não aceitas pelo servidor selecionado (p. ex., collation, readConcern, writeConcern).

MongoDB\Exception\InvalidArgumentException para erros relacionados à análise de parâmetros ou opções.

MongoDB\Driver\Exception\RuntimeException para outros erros no nível da extensão (por exemplo erros de conexão).

Exemplos

Este exemplo relata eventos enquanto itera um change stream.

<?php
$uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
$client = new MongoDB\Client($uri);
$changeStream = $client->watch();
for ($changeStream->rewind(); true; $changeStream->next()) {
    if ( ! $changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    if ($event['operationType'] === 'invalidate') {
        break;
    }
    $ns = sprintf('%s.%s', $event['ns']['db'], $event['ns']['coll']);
    $id = json_encode($event['documentKey']['_id']);
    switch ($event['operationType']) {
        case 'delete':
            printf("Deleted document in %s with _id: %s\n\n", $ns, $id);
            break;
        case 'insert':
            printf("Inserted new document in %s\n", $ns);
            echo json_encode($event['fullDocument']), "\n\n";
            break;
        case 'replace':
            printf("Replaced new document in %s with _id: %s\n", $ns, $id);
            echo json_encode($event['fullDocument']), "\n\n";
            break;
        case 'update':
            printf("Updated document in %s with _id: %s\n", $ns, $id);
            echo json_encode($event['updateDescription']), "\n\n";
            break;
    }
}

Supondo que um documento tenha sido inserido, atualizado e excluído enquanto o script acima iterava o change stream, a saída seria semelhante a:

Inserted new document in app.user
{"_id":{"$oid":"5b329b6674083047cc05e607"},"username":"bob"}
Inserted new document in app.products
{"_id":{"$oid":"5b329b6a74083047cc05e608"},"name":"Widget","quantity":5}
Inserted new document in logs.messages
{"_id":{"$oid":"5b329b7374083047cc05e609"},"msg":"bob purchased a widget"}

Veja também

MongoDB\Collection::watch()
MongoDB\Database::watch()
Documentação do aggregation pipeline no Manual do MongoDB
Documentação do Change Streams no Manual do MongoDB
Documentação de eventos de alterações no manual do MongoDB

Voltar

startSession()

MongoDB\reconhecimento de data center