(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:
"w"
Véase WriteConcerns. El valor predeterminado de MongoClient es 1.
"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. Fuerza a la inserción a estar sincronizada con el disco antes de devolver éxito. Si es TRUE, está implicada una inserción declarada y sobrescribirá el ajuste w a 0.
"timeout"
Entero, su valor predeterminado es MongoCursor::$timeout. Si se establece a "safe", establece cuánto espera el cliente (en milisegundos) a un respuesta de la base de datos. Si la base de datos no responde dentro del periodo del tiempo de espera, será lanzada una MongoCursorTimeoutException.
"safe"
Obsoleto. Use la opción w de WriteConcern.
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.