(PECL mongo >=0.9.0)
MongoCollection::update — Actualizar registros basándose en los criterios proporcionados
$criteria
, array $new_object
[, array $options
= array()
] )
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.
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().
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.
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).
|
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)
);
?>
La documentación de PHP sobre actualizaciones y la » documentacion en MongoDB.