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	O número máximo de documentos dentro de cada lote retornados em um change stream, que se aplica ao comando aggregate. Por padrão, o comando aggregate tem um tamanho de lote inicial de 101 documentos e um tamanho máximo de 16 mebibytes (MiB) para cada lote subsequente. Esta opção pode impor um limite menor que 16 MiB, mas não maior. Se você definir batchSize para um limite que resulte em lotes maiores que 16 MiB, essa opção não terá efeito. 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	Os codificam dados com codecs de tipo a serem usados 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 a partir de 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. A partir do MongoDB 6.0, você pode acessar a pós-imagem do documento modificado se a coleção tiver changeStreamPreAndPostImages ativado. Especifique whenAvailable para retornar a pós-imagem, se disponível, ou um valor nulo, caso contrário. Especifique "obrigatório" para retornar a pós-imagem, se disponível, ou gerar um erro, caso contrário. 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. 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 registro de data/hora especificado ou após. 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. Para usar esta opção, você deve se conectar ao MongoDB 6.0 ou posterior. Se você estiver conectado a uma versão anterior, o servidor retornará uma exceção no tempo de execução. Esta é uma opção do estágio do pipeline $changeStream .
typeMap	array	O mapa de tipo a aplicar aos cursores, 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 MongoDB\ChangeStream, que permite a iteração de eventos no fluxo de alterações por meio da interface do Iterador.

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