/ /

/ /

Librerías de clientes

PHP

Biblioteca PHP

MongoDB\Colección

MongoDB\Collection::watch()

Nuevo en la versión 1.3.

Definición

MongoDB\Collection::watch()

Ejecuta una Operación deflujo de cambios en la colección. Se puede supervisar el flujo de cambios para detectar cambios a nivel de colección.

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

Parámetros

$pipeline : matriz|objeto

La secuencia de etapas que se agregarán a una etapa inicial $changeStream.

$options : matriz

Una matriz que especifica las opciones deseadas.

Nombre	Tipo	Descripción
tamaño del lote	entero	El número máximo de documentos dentro de cada lote devuelto en un flujo de cambios, que se aplica al comando `aggregate`. De forma predeterminada, el comando `aggregate` tiene un tamaño de lote inicial de `101` documentos y un tamaño máximo de 16 mebibytes (MiB) para cada lote posterior. Esta opción puede imponer un límite inferior a 16 MiB, pero no superior. Si se establece `batchSize` en un límite que resulte en lotes superiores a 16 MiB, esta opción no tiene efecto. Independientemente de la opción `batchSize`, la respuesta del comando `aggregate` inicial para un flujo de cambios generalmente no incluye ningún documento a menos que se utilice otra opción para configurar su punto de inicio (por ejemplo, `startAfter`).
codec	MongoDB\Códec\DocumentCodec	El Codificar datos con códecs de tipo para codificar o decodificar documentos. Esta opción es mutuamente excluyente con la `typeMap` opción. El valor predeterminado es el códec de la colección. La herencia de la opción predeterminada `codec` prevalece sobre la de la opción `typeMap`. Nuevo en la versión 1.17.
intercalación	matriz\|objeto	Laintercalación permite a los usuarios especificar reglas específicas del idioma para la comparación de cadenas, como el uso de mayúsculas y minúsculas y tildes. Al especificar la intercalación, el `locale` campo es obligatorio; todos los demás campos son opcionales. Para obtener descripciones de los campos, consulte el documento de intercalación. Esta opción tiene como opción predeterminada una comparación binaria simple si se omite.
comment	mixto	Permite a los usuarios especificar un comentario arbitrario para ayudar a rastrear la operación a través del generador de perfiles de base de datos, la salidacurrentOp y los registros. El comentario puede ser cualquier tipo BSON válido a partir de MongoDB 4.4. Las versiones anteriores del servidor solo admiten valores de cadena. Novedades en la versión 1.13.
documento completo	string	Determina cómo se completará el campo de respuesta `fullDocument` para las operaciones de actualización. De forma predeterminada, los flujos de cambio solo devuelven la delta de los campos (mediante un campo `updateDescription`) para las operaciones de actualización, y se omite `fullDocument`. Las operaciones de inserción y reemplazo siempre incluyen el campo `fullDocument`. Las operaciones de eliminación omiten el campo, ya que el documento ya no existe. Especifique "updateLookup" para devolver la versión mayoritariamente confirmada actual del documento actualizado. A partir de MongoDB 6.0, puede acceder a la imagen posterior del documento modificado si la colección tiene habilitado `changeStreamPreAndPostImages`. Especifique `whenAvailable` para devolver la imagen posterior si está disponible o un valor nulo si no lo está. Especifique "required" para devolver la imagen posterior si está disponible o generar un error si no lo está. Se admiten los siguientes valores: `MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP` `MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE` `MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED` Esta es una opción de la etapa de canalización `$changeStream`.
Documento completo antes del cambio	string	Determina cómo se rellenará el campo de respuesta `fullDocumentBeforeChange`. Por defecto, este campo se omite. MongoDB 6.0+ permite devolver la preimagen del documento modificado si la colección tiene `changeStreamPreAndPostImages` habilitado. Especifique "whenAvailable" para devolver la preimagen si está disponible o un valor nulo si no lo está. Especifique "required" para devolver la preimagen si está disponible o generar un error si no lo está. Se admiten los siguientes valores: `MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE` `MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED` Esta es una opción de la etapa de canalización `$changeStream`. Novedades en la versión 1.13.
maxAwaitTimeMS	entero	Entero positivo que indica el límite de tiempo en milisegundos para que el servidor bloquee una operación getMore si no hay datos disponibles.
readConcern	MongoDB\Driver\ReadConcern	Preocupación de lectura para la operación. El valor predeterminado es la preocupación de lectura de la colección.
readPreference	MongoDB\Controlador\Preferencia de lectura	Preferencia de lectura para la operación. El valor predeterminado es la preferencia de lectura de la colección. Esto se utiliza tanto para la agregación del flujo de cambio inicial como para la selección del servidor durante una reanudación automática.
reanudarDespués	matriz\|objeto	Especifica el punto de inicio lógico para el nuevo flujo de cambios. Aquí se puede usar el campo `_id` en los documentos devueltos por el flujo de cambios. Usar esta opción junto con `startAfter` o `startAtOperationTime` provocará un error del servidor. Las opciones son mutuamente excluyentes. Esta es una opción de la etapa de canalización `$changeStream`.
sesión	MongoDB\Controlador\Sesión	Sesión de cliente para asociar a la operación.
mostrarEventosExpandidos	booleano	Si es verdadero, indica al servidor que incluya eventos DDL adicionales en el flujo de cambios. Los eventos adicionales que se pueden incluir son: `createIndexes` `dropIndexes` `modify` `create` `shardCollection` `reshardCollection` (servidor 6.1+) `refineCollectionShardKey` (servidor 6.1+) Esto no es compatible con versiones de servidor anteriores a 6.0 y generará una excepción en el momento de ejecución si se utiliza. Esta es una opción de la etapa de canalización `$changeStream`. Novedades en la versión 1.13.
empezarDespués	matriz\|objeto	Especifica el punto de inicio lógico para el nuevo flujo de cambios. El campo `_id` en los documentos devueltos por el flujo de cambios puede usarse aquí. A diferencia de `resumeAfter`, esta opción puede utilizarse con un token de reanudación de un evento de "invalidación". Usar esta opción junto con `resumeAfter` o `startAtOperationTime` provocará un error del servidor. Las opciones son mutuamente excluyentes. Esta es una opción de la etapa de canalización `$changeStream`. Nuevo en la versión 1.5.
iniciarEnTiempoDeOperación	MongoDB\BSON\TimestampInterface	Si se especifica, el flujo de cambios solo proporcionará los cambios ocurridos en la fecha y hora especificadas o después. De forma predeterminada, se usará el valor `operationTime` devuelto por el comando `aggregate` inicial, si está disponible. Usar esta opción junto con `resumeAfter` o `startAfter` provocará un error del servidor. Las opciones son mutuamente excluyentes. Para usar esta opción, debe conectarse a MongoDB 6.0 o una versión posterior. Si está conectado a una versión anterior, el servidor devuelve una excepción durante la ejecución. Esta es una opción de la etapa de canalización `$changeStream`.
typeMap	arreglo	El mapa de tipos que se aplica a los cursores y que determina cómo se convierten los documentos BSON a valores PHP. El valor predeterminado es el mapa de tipos de la colección.

Return Values

Un objeto que permite la iteración de eventos en el flujo de cambios a través de MongoDB\ChangeStream la interfaz Iterator.

Errores/Excepciones

MongoDB\Exception\UnexpectedValueException si la respuesta del comando del servidor era incorrecta.

MongoDB\Exception\UnsupportedException si se utilizan opciones que no son compatibles con el servidor seleccionado (porcollation readConcernwriteConcernejemplo,,,).

MongoDB\Exception\InvalidArgumentException para errores relacionados con el análisis de parámetros u opciones.

MongoDB\Driver\Exception\RuntimeException para otros errores en el nivel de extensión (por ejemplo, errores de conexión).

Ejemplos

Este ejemplo informa eventos mientras se itera un flujo de cambios.

<?php
$uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
$collection = (new MongoDB\Client($uri))->test->inventory;
$changeStream = $collection->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;
    }
}

Suponiendo que se insertó, actualizó y eliminó un documento mientras el script anterior iteraba el flujo de cambios, el resultado sería similar a lo siguiente:

Inserted new document in test.user
{"_id":{"$oid":"5b329c4874083047cc05e60a"},"username":"bob"}
Inserted new document in test.products
{"_id":{"$oid":"5b329c4d74083047cc05e60b"},"name":"Widget","quantity":5}
Updated document in test.user with _id: {"$oid":"5b329a4f74083047cc05e603"}
{"updatedFields":{"username":"robert"},"removedFields":[]}

Ver también

MongoDB\Client::watch()
MongoDB\Database::watch()
Documentación de lacanalización de agregación en el Manual de MongoDB
Documentación de flujos de cambios en el manual de MongoDB
Documentación de eventos de cambio en el manual de MongoDB

Volver

actualizarSearchIndex()

conOpciones()