MongoDB\Collection::watch()

Definición

MongoDB\Collection::watch()

Ejecuta un(a) flujo de cambios operación en la colección. El flujo de cambios puede ser monitoreado para cambios a nivel de colección.

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

Parámetros

$pipeline : arreglo|objeto

El pipeline de etapas que se va a añadir a una etapa inicial $changeStream.

$options : arreglo

Un arreglo que especifica las opciones deseadas.

Nombre	Tipo	Descripción
batchSize	entero	El número máximo de documentos dentro de cada lote devuelto en un flujo de cambios, que se aplica al comando aggregate. Por defecto, 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 aplicar un límite menor que 16 MiB, pero no uno mayor. Si configuras batchSize en un límite que origine lotes más grandes que 16 MiB, esta opción no tendrá efecto. Independientemente de la opción batchSize, la respuesta inicial del comando aggregate para un flujo de cambios no suele incluir ningún documento a menos que se utilice otra opción para configurar su punto de inicio (por ejemplo, startAfter).
códec	MongoDB\Codec\DocumentCodec	La Codifica datos con códecs de tipo para usar en la codificación o decodificación de documentos. Esta opción es mutuamente excluyente con la opción typeMap. Se configura de forma predeterminada al códec de la colección. La herencia para una opción codec por defecto tiene prioridad sobre la de la opción typeMap. Novedad en la versión 1.17.
intercalación	arreglo|objeto	Intercalación permite a los usuarios especificar reglas específicas del lenguaje para la comparación de cadenas, tales como reglas para mayúsculas y tildes. Al especificar la intercalación, el campo locale es obligatorio; todos los demás campos de intercalación son opcionales. Para obtener descripciones de los campos, consulte Documento de intercalación. Esta opción se configura por defecto en la 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 perfilador de bases de datos, la salida actualOp() y registros. El comentario puede ser cualquier tipo válido de BSON a partir de MongoDB 4.4. Las versiones anteriores del servidor solo admiten valores de string. Novedades en la versión 1.13.
fullDocument	string	Determina cómo se llenará el campo de respuesta fullDocument para las operaciones de actualización. Por defecto, los flujos de cambio solo devuelven el delta de los campos (a través de un campo updateDescription) para las operaciones de actualización y fullDocument se omite. Las operaciones de inserción y reemplazo siempre incluyen el campo fullDocument. Las operaciones de borrar omiten el campo, ya que el documento ya no existe. Especifica "updateLookup" (búsqueda de actualización) para devolver la versión actual confirmada por mayoría del documento actualizado. A partir de MongoDB 6.0, puedes acceder a la post-imagen del documento modificado si la colección tiene activada la changeStreamPreAndPostImages. Especifique whenAvailable para devolver la imagen de publicación si está disponible o un valor nulo si no lo está. Especifique "required" para devolver la imagen de publicación 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 pipeline $changeStream.
fullDocumentBeforeChange	string	Determina cómo se completará el campo de respuesta fullDocumentBeforeChange. Por defecto, el campo se omite. MongoDB 6.0+ permite devolver la pre-imagen del documento modificado si la colección tiene changeStreamPreAndPostImages habilitado. Especifica "whenAvailable" para devolver la preimagen si está disponible o un valor nulo si no lo está. Especifica "requerido" para devolver la preimagen si está disponible o generar un error en caso contrario. 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 pipeline $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	Nivel de consistencia de lectura para usar en la operación. Por defecto, adopta el nivel de consistencia de lectura de la colección.
readPreference	MongoDB\Driver\ReadPreference	Preferencia de lectura a utilizar para la operación. Por defecto, se utiliza la preferencia de lectura de la colección. Esto se utiliza tanto para la agregación inicial de flujos de cambio como para la selección del servidor durante una reanudación automática.
Reanudar después	arreglo|objeto	Especifica el punto de partida lógico para el nuevo flujo de cambios. El campo _id en los documentos devueltos por el flujo de cambios puede usarse aquí. Utilizar esta opción en conjunto con startAfter y/o startAtOperationTime provocará un error del servidor. Las opciones son mutuamente excluyentes. Esta es una opción de la etapa de pipeline $changeStream.
sesión	MongoDB\Driver\Session	Sesión de cliente para asociar con la operación.
mostrarEventosExpandido	booleano	Si es verdadero, indica al servidor que incluya eventos DDL adicionales en el flujo de cambios. Se pueden incluir los siguientes eventos adicionales: createIndexes dropIndexes modify create shardCollection reshardCollection (servidor 6.1+) refineCollectionShardKey (servidor 6.1+) Esto no se admite en versiones anteriores del servidor a la 6.0 y, si se utiliza, provocará una excepción en el momento de la ejecución. Esta es una opción de la etapa de pipeline $changeStream. Novedades en la versión 1.13.
startAfter	arreglo|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". Utilizar esta opción en conjunto con resumeAfter y/o startAtOperationTime provocará un error del servidor. Las opciones son mutuamente excluyentes. Esta es una opción de la etapa de pipeline $changeStream. Nueva en la versión 1.5.
startAtOperationTime	MongoDB\BSON\TimestampInterface	Si se especifica, el flujo de cambios solo proporcionará los cambios que ocurrieron en o después de la marca de tiempo especificada. Por defecto, se utilizará el operationTime devuelto por el comando inicial aggregate, si está disponible. Utilizar esta opción en conjunto con resumeAfter y/o startAfter provocará un error del servidor. Las opciones son mutuamente excluyentes. Para utilizar esta opción, debes conectarte a MongoDB 6.0 o posterior. Si está conectado a una versión anterior, el servidor devuelve una excepción al momento de la ejecución. Esta es una opción de la etapa de pipeline $changeStream.
typeMap	arreglo	El mapa de tipos para aplicar a cursores, que determina cómo se convierten los documentos BSON en valores PHP. Por defecto, se utiliza el mapa de tipos de la colección.

Return Values

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

Errores/Excepciones

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

MongoDB\Exception\UnsupportedException si se usan opciones que no sean compatibles con el servidor seleccionado (p. ej. collation, readConcern, writeConcern).

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

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

Ejemplos

Este ejemplo informa sobre eventos mientras recorre 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 insertara, actualizara y eliminara un documento mientras el script anterior estuviese iterando el flujo de cambios, la salida se parecería entonces a:

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()

• Pipelines de agregación documentación en el Manual de MongoDB

• Change Streams documentación en el manual de MongoDB

• Documentación sobre Change eventos en el manual de MongoDB