MongoDB\Database::watch()

Definição

MongoDB\Database::watch()

Executa uma operação dechange stream do no banco de dados. O change stream pode ser observado quanto a alterações no nível do banco de dados.

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	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 banco de dados.
readPreference	MongoDB\Driver\ReadPreference	Preferência de leitura a ser usada na operação. O padrão é a preferência de leitura do banco de dados. 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 banco de dados.

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';
$database = (new MongoDB\Client($uri))->test;
$changeStream = $database->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 test.inventory
{"_id":{"$oid":"5a81fc0d6118fd1af1790d32"},"name":"Widget","quantity":5}
Updated document in test.inventory with _id: {"$oid":"5a81fc0d6118fd1af1790d32"}
{"updatedFields":{"quantity":4},"removedFields":[]}
Deleted document in test.inventory with _id: {"$oid":"5a81fc0d6118fd1af1790d32"}

Veja também

• MongoDB\Collection::watch()

• MongoDB\Client::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