MongoDB\Collection::watch()

Definición

MongoDB\Collection::watch()

Ejecuta una 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

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

$options : arreglo

Una matriz 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 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. Novedad en la versión 1.17.
intercalación	arreglo|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 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 generador de perfiles de base de datos, la salidacurrentOp y los 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. 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. 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 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, si se utiliza, generará una excepción en el momento de 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 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. 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 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 por 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 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 de eventos de cambio en el manual de MongoDB