MongoDB\Client::watch()

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.
comentário	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.

Valores de retorno

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