MongoCollection
PHP Manual

MongoCollection::update

(PECL mongo >=0.9.0)

MongoCollection::updateActualizar registros basándose en los criterios proporcionados

Descripción

public bool|array MongoCollection::update ( array $criteria , array $new_object [, array $options = array() ] )

Parámetros

criteria

Descripción de los objetos a actualizar.

new_object

El objeto con el que actualizar los registros que cumplan las condiciones.

options

Este parámetro es un array asociativo de la forma array("optionname" => <boolean>, ...). Las opciones soportadas actualmente son:

  • "upsert"

    Si ningún documento cumplira las condiciones de $criteria, se crearía un nuevo documento a partir de $criteria y $new_object (revise más abajo el ejemplo de upsert).

  • "multiple"

    Todos los documentos que cumplan las condiciones de $criteria se actualizarán. MongoCollection::update() tiene exactamente el comportamiento contrario que MongoCollection::remove(): de forma predeterminada, actualiza sólo un documento, no todos los que cumplan las condiciones. Se recomienda especificar siempre se si deben actualizar múltiples documentos o un único documento, ya que el comportamiento predeterminado de la base de datos podría cambiar en el futuro.

  • "safe"

    Puede ser un booleano o un entero, por omisión FALSE. Si FALSE, el programa continua su ejecución sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperará la respuesta de la base de datos y emitira una excepcion MongoCursorException si la inserción no tuviera éxito.

    Si se estuvieran utilizando réplicas, y el maestro cambiara, al usar "safe" se provocaría que el driver desconectaría del maestro, emitiría una excepción, y en la siguiente operación se tratría de encontrar un nuevo maestro (su aplicación debe decidir si reintentará realizar de nuevo la operación sobre un nuevo maestro).

    Si no utiliza "safe" con conjuntos de réplicas y el maestro cambia, no habrá forma de que el driver conozca el cambio. En este caso, continuará la ejecución y la escritura, silenciosamente, fallará.

    Si safe fuera un entero, replicará la actualización a ese número de máquinas antes de notificar un éxito (o lanzaría una excepción si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la colección.

  • "fsync"

    Booleano, por omisión FALSE. Obliga a que la actualización se sincronice en disco antes de notificar éxito. Si TRUE, se realiza de manera implícita una actuaización segura (safe) y sobrescribirá el ajuste safe a FALSE.

  • "timeout"

    Entero, por omisión MongoCursor::$timeout. Si "safe" está habilitado, este valor indica por cuánto tiempo (en milisegundos) esperará el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo de tiempo, se lanzaría una excepción de tipo MongoCursorTimeoutException.

Valores devueltos

Si safe está habilitado, devuelve un array con el estado de la actualización. En cualquier otro caso, devuelve un booleano indicando si el array no estaba vacío (un array vacío no se insertará). Los campos de este array están descritos en la documentación de MongoCollection::insert().

Errores/Excepciones

Lanza MongoCursorException si la opción "safe" estuviera habilitada y la actualización fallara.

Lanza MongoCursorTimeoutException si la opción "safe" estuviera habilitada y a la operación llevara más de MongoCursor::$timeout milisegundos completarse. No detiene el proceso en el servidor; es sólo un tiempo de espera en el lado del cliente.

Historial de cambios

Versión Descripción
1.0.1 Cambiado el parámetro "opciones" de un booleano a un array. Antes de 1.0.1, el segundo parámetro era un booleano opcional cuyo valor indicaba si era o no upsert.
1.0.5 Añadida la opción "safe".
1.0.9 Añadido soporte para pasar enteros a la opción "safe" (antes sólo aceptaba booleanos) y añadida la opción "fsync".
1.0.9 Cambiado el tipo devuelto por un array que contiene información del error si se utiliza la opción "safe", de otro modo es un booleano como antes.
1.0.11 Si "safe" está habilitado y hay un error que no sea en el maestro, se desconecta.
1.2.0 Añadida la opción "timeout".
1.2.11 Emite E_DEPRECATED cuando options es de tipo scalar.
1.3.0 El parámetro options no acepta un valor booleano para indicar un upsert. En su lugar, esto ahora se tiene que hacer con array('upsert' => true).

Ejemplos

Ejemplo #1 MongoCollection::update()

Añadiendo el campo dirección a un documento

<?php

$c
->insert(array("nombre" => "Pedro""apellido" => "Ruiz" ));
$nuevosdatos = array('$set' => array("direccion" => "Calle Juan, 1"));
$c->update(array("nombre" => "Pedro"), $nuevosdatos);

var_dump($c->findOne(array("nombre" => "Pedro")));

?>

El resultado del ejemplo sería algo similar a:

array(4) {
  ["_id"]=>
  object(MongoId)#6 (0) {
  }
  ["nombre"]=>
  string(3) "Pedro"
  ["apellido"]=>
  string(5) "Ruiz"
  ["direccion"]=>
  string(12) "Calle Juan, 1"
}

Ejemplo #2 Ejemplo de MongoCollection::update() con upsert

Los upserts pueden simplificar el código, ya que con una sóla línea podemos crear el objeto si éste no existiera, o actualizarlo si existiera.

<?php

$c
->drop();
$c->update(array("uri" => "/fotos_verano"), array('$inc' => array("accesos" => 1)), array("upsert" => true));
var_dump($c->findOne());

?>

El resultado del ejemplo sería algo similar a:

array(3) {
  ["_id"]=>
  object(MongoId)#9 (0) {
  }
  ["uri"]=>
  string(12) "/fotos_verano"
  ["accesos"]=>
  int(1)
}

Si $new_object no contuviera operadores $, upsert podría crear a partir de él un nuevo documento. Esto coincide con el comportamiento normal de una actualización: si no se usaran operadores $, se sobrescribiría todo el documento.

<?php

$c
->drop();
$c->update(
    array(
"name" => "joe"),
    array(
"username" => "joe312""createdAt" => new MongoDate()), 
    array(
"upsert" => true)
);
var_dump($c->findOne());

?>

El resultado del ejemplo sería algo similar a:

array(3) {
  ["_id"]=>
  object(MongoId)#10 (0) {
  }
  ["usuario"]=>
  string(6) "juan312"
  ["fechaAlta"]=>
  object(MongoDate)#4 (0) {
  }
}

Ejemplo #3 Ejemplo de múltiples MongoCollection::update()

De forma predeterminada, MongoCollection::update() sólo actualizará el primer documento que encuentre que cumpla las condiciones de $criteria. Si fuera necesario, mediante la opción "multiple" podremos sobrescribir este comportamiento.

Este ejemplo añade un campo "regalo" a cada persona cuyo cumpleaños sea el próximo día.

<?php

$today 
= array('$gt' => new MongoDate(), '$lt' => new MongoDate(strtotime("+1 day")));
$people->update(
    array(
"birthday" => $today),
    array(
'$set' => array('gift' => $surprise)),
    array(
"multiple" => true)
);

?>

Ver también

La documentación de PHP sobre actualizaciones y la » documentacion en MongoDB.


MongoCollection
PHP Manual