(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 cumple las condiciones de $criteria, se
insertará un nuevo documento.
Si se insertara un nuevo documento y
$new_object contiene modificadores atómicos
(esto es, operadores $), esas operaciones serán
aplicadas al parámetro $criteria para crear
el nuevo documento. Si $new_object no
contiene modificadores atómicos, será utilizado tal cual para el documento
insterdo. Véase los ejemplos de upsert abajo para más información.
"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.
"fsync"
Booleano, su valor predeterminado es FALSE. Si la opción "journal" está habilitada, funciona exactamente como "j". Si no está habilitada, fuerza a la inserción que sea sincronizada con el disco antes de devolver que tuvo éxito. Si es TRUE, está implicada una inserción reconocida y sobrescribirá el ajuste w a 0.
Nota:
Esta opción está obsoleta. Use la opción "j" en su lugar.
"j"
Booleano, su valor predeterminado es FALSE. Fuerza a la inserción a ser sincronizada con el diario antes de devolver que ha tenido éxito. Si es TRUE, implica una inserción reconocida y sobrescribirá el ajuste w a 0.
"w"
Véase WriteConcerns. El valor predeterminado de MongoClient es 1.
"wtimeout"
Cuánto esperar para el reconocimiento de WriteConcern. El valor predeterminado de MongoClient es 10000 milisegundos.
"safe"
Obsoleto. Use la opción w de WriteConcern.
"timeout"
Entero, valor predeterminado MongoCursor::$timeout. Si se usan las escrituras reconocidas, esto estable cuánto debe esperar el cliente (en milisegundos) a una respuesta de la base de datos. Si la base de datos no responde dentro de perído de espera, se lanzará una MongoCursorTimeoutException.
Devuelve un array que contiene el estado de la actualización si la
opción "w" está establecida. De lo contrario, devuelve TRUE.
Los campos del array de estado están descritos en la documentación para MongoCollection::insert().
Lanza una MongoCursorException si la opción "w" está establecida y la escritura falla.
Lanza una MongoCursorTimeoutException si la opción "w" está establecida a un valor mayor que uno y la operación toma más de MongoCursor::$timeout milisegundos en completarse. Esto no pondrá fin a la operación en el servidor, es un tiempo de espera del lado del cliente. La operación en MongoCollection::$wtimeout es milisegundos.
| Versión | Descripción |
|---|---|
| 1.3.0 |
El parámetro options ya no acepta un valor booleano
para indicar un upsert. En su lugar, esto ahora se tiene que hacer
con array('upsert' => true).
|
| 1.2.11 |
Emite E_DEPRECATED cuando
options es de tipo scalar.
|
| 1.2.0 | Se añadió la opción "timeout". |
| 1.0.11 | Se desconecta en errores "not master" si "safe" está establecido. |
| 1.0.9 |
Añadida la capacidad de pasar enteros a la opción "safe", la cual anteriormente únicamente aceptaba booleanos. Añadida la opción "fsync". Cambiado el tipo devuelto por un array que contiene información si se utiliza la opción "safe". De otro modo, se devuelve un booleano como antes. |
| 1.0.5 | Se añadió la opción "safe". |
| 1.0.1 |
Cambiado el parámetro "opciones" de un booleano a un array.
Antes de la versión 1.0.1, el segundo parámetro era valor booleano opcional especificando
un upsert.
|
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 Ejemplos de MongoCollection::update() con upsert
Los upserts pueden simplificar el código, ya que con una única línea se puede crear el documento si
no existe (basado en $criteria), o actualizar un
documento existente si coincide.
En el siguiente ejemplo, $new_object contiene un
modificador atómico. Ya que la colección está vacía y upsert debe insertar un nuevo
documento, aplicará esas operaciones al
parámetro $criteria para crear el documento.
<?php
$c->drop();
$c->update(
array("uri" => "/summer_pics"),
array('$inc' => array("page hits" => 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 contiene modificadores atómicos
(esto es, operadores $), upsert utilizará
$new_object tal cual para el nuevo documento. Esto coincide
con el comportamiento de una actualización normal, donde la no utilización de modificadores atómicos
ocasiona la sobrescritura del 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.