Operaciones con desarrolladores

Overview

En esta guía, puedes aprender sobre las clases desarrolladoras que la librería PHP proporciona para crear tipos utilizados en tus operaciones. Puedes utilizar las clases builder y los métodos de fábrica de la funcionalidad Aggregation Builder para crear filtros para otras operaciones como find, actualizar y borrar operations. Para obtener más información sobre el Constructor de agregación, consulte el Constructor de agregaciones de la guía de Agregación.

Utilizar desarrolladores para crear queries ayuda a identificar errores en tiempo de compilación y a evitarlos en tiempo de ejecución. Esta guía proporciona información sobre las clases de desarrollador que puedes usar para realizar las siguientes tareas:

• Crear un filtro

• Definir un Documento de actualización

• Modifica la salida del flujo de cambios

$options = [
    'limit' => 5,
    '<option name>' => '<specification>',
];

Esta guía proporciona ejemplos de cómo usar desarrolladores en operaciones que no son de agregación. Para ver ejemplos de agregación, consulta la guía Operaciones de agregación.

$collection = $client->sample_geospatial->shipwrecks;

Importar clases de desarrolladores

Para ejecutar los ejemplos en esta guía, debes importar las siguientes clases en tu aplicación:

use MongoDB\Builder\Pipeline;
use MongoDB\Builder\Query;
use MongoDB\Builder\Stage;

Crear un filtro

Puedes usar los métodos de fábrica de la clase de generador Query para crear definiciones de filtros que se utilicen en las operaciones de búsqueda, actualización y eliminación. Cuando utilices el método de fábrica Query::query() para crear consultas, puedes utilizar la sintaxis de argumentos nombrados e implementar la seguridad de tipos. Para obtener más información sobre cómo crear filtros, consulta la guía Especificar una query.

Los siguientes pasos describen cómo crear una definición de filtro utilizando los desarrolladores:

1. Llame al método Query::query() para crear una consulta.

2. Pasa el nombre del campo para el filtro y un método de fábrica de la clase Query. Puedes pasar uno o más pares de nombres de campos y criterios en el filtro para aplicar múltiples cláusulas.

El siguiente código muestra la plantilla para crear una definición de filtro utilizando desarrolladores:

$filter = Query::query(
    <field name>: Query::<factory method>(<parameters>),
    <field name>: Query::<factory method>(<parameters>),
    ...
);

Para combinar criterios del query mediante operadores lógicos del query ($and, $or, $not, $nor), puedes utilizar la siguiente plantilla del query:

$filter = Query::<logical operator>(
    Query::query(<field name>: Query::<factory method>(<parameters>)),
    Query::query(<field name>: Query::<factory method>(<parameters>)),
    ...
);

Para obtener más información, consulte Operadores lógicos de consulta en el manual de MongoDB Server.

Las siguientes secciones proporcionan ejemplos que utilizan desarrolladores para crear definiciones de filtros para diferentes operaciones.

// Creates a query filter by using builders and
// retrieves matching documents
$docs = $collection->find(
    Query::query(
        feature_type: Query::eq('Wrecks - Visible'),
        coordinates: Query::near(
            Query::geometry(
                type: 'Point',
                coordinates: [-79.9, 9.3],
            ),
            maxDistance: 10000,
        ),
    ),
);
// Prints matching documents
foreach ($docs as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9137115,9.3390503],...}
{"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9357223,9.3340302],...}
{"_id":...,"feature_type":"Wrecks - Visible","coordinates":[-79.9081268,9.3547792],...}
// Results truncated

// Creates a query filter by using builders
// and deletes the first matching document
$result = $collection->deleteOne(
    Query::or(
        Query::query(feature_type: Query::regex('nondangerous$', '')),
        Query::query(depth: Query::gt(10.0)),
    ),
);
// Prints number of deleted documents
echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;

Deleted documents: 1

Definir un Documento de actualización

Puede utilizar métodos de fábrica de la clase constructora Stage para crear documentos de actualización. Actualiza los documentos que describen las actualizaciones a realizar en los documentos objetivo. Para obtener más información sobre cómo actualizar documentos, consulta la guía Actualizar documentos.

Los siguientes pasos describen cómo crear un documento de actualizar utilizando desarrolladores:

1. Crea una instancia de Pipeline.

2. Aprobar una o más etapas llamando los métodos de la clase Stage, como Stage::set(), y pasando nombres de campo y valores.

El siguiente código muestra la plantilla para definir una actualización mediante el uso de desarrolladores:

$update = new Pipeline(
    Stage::set(<field name>: <value>),
    Stage::set(<field name>: <value>),
    ...
);

Este ejemplo realiza las siguientes acciones:

• Utiliza el método de fábrica Query::eq() para hacer coincidir documentos en los que el valor del campo watlev es 'partly submerged at high water'

• Utiliza el método Stage::set() para establecer el campo year en 1870

• Llama al método MongoDB\Collection::updateOne() para realizar la actualización

• Imprime el número de documentos actualizados

// Creates a query filter and an update document by
// using builders and updates the first matching document
$result = $collection->updateOne(
    Query::query(watlev: Query::eq('partly submerged at high water')),
    new Pipeline(
        Stage::set(year: 1870),
    ),
);
// Prints number of updated documents
echo 'Updated documents: ', $result->getModifiedCount(), PHP_EOL;

Updated documents: 1

Modifica la salida del flujo de cambios

Puede usar métodos de fábrica de la clase Stage para modificar la salida de un flujo de cambios creando un pipeline. Para obtener más información acerca de Change Streams, consulte la Guía para monitorizar datos con Change Streams.

Los siguientes pasos describen cómo crear un filtro de flujo de cambios utilizando desarrolladores:

1. Crea un arreglo.

2. Pasa una o más etapas de $match llamando a los métodos de fábrica de la clase Stage y los parámetros requeridos.

El siguiente código muestra la plantilla para modificar la salida de los flujos de cambios usando constructores:

$pipeline = [
    Stage::<factory method>(...),
    Stage::<factory method>(...),
    ...
];

Puedes pasar esta pipeline a los siguientes métodos:

• MongoDB\Client::watch()

• MongoDB\Database::watch()

• MongoDB\Collection::watch()

Este ejemplo realiza las siguientes acciones:

• Utiliza el método Stage::match() para filtrar únicamente los eventos de cambio en operaciones de actualización

• Utiliza el método Stage::project() para mostrar solo los campos operationType, ns (namespace) y fullDocument

• Llama al método MongoDB\Collection::watch() para abrir el flujo de cambios y establece la opción fullDocument para mostrar el documento completo después de la actualización

• Imprime eventos de cambio a medida que ocurren

// Creates a pipeline to filter for update operations and return
// only specific fields
$pipeline = [
    Stage::match(operationType: Query::eq('update')),
    Stage::project(operationType: 1, ns: 1, fullDocument: 1),
];
// Opens the change stream
$changeStream = $collection->watch(
    $pipeline,
    ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP],
);
// Prints change events based on the pipeline specifications
for ($changeStream->rewind(); true; $changeStream->next()) {
    if (! $changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    echo json_encode($event), PHP_EOL;
    if ($event['operationType'] === 'invalidate') {
        break;
    }
}

{
  "_id":...,
  "operationType":"update",
  "fullDocument":{"_id":...,"feature_type":"Wrecks - Visible",...},
  "ns":{"db":"sample_geospatial","coll":"shipwrecks"}
}

Para obtener más información sobre los datos proporcionados por los eventos de cambio, consulte Eventos de Cambio en el manual de MongoDB Server.