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

Criterios de consulta para los documentos a actualizar.

new_object

El objeto usado para actualizar los documentos coincidentes. Podría contener operadores de actualización (para modificar campos específicos) o ser un documento de remplazo.

options

Un array de opciones para la operación de actualización. Las opciones disponibles 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, cuyo valor predeterminado es FALSE. Si el registro en el diario está habilitado, funciona exactamente igual que "j". Si no está habilidato, la operación de escriturá bloqueará hasta que se sincronice con los ficheros de la base de datos del disco. Si es TRUE, implica una inserción reconocida y sobrescribirá el ajuste "w" a 0.

    Nota: Si está habilitada, se recomienda a los usuarios usar la opción "j" en lugar de "fsync". No use "fsync" y "j" simultáneamente, ya que resultará en un error.

  • "j"

    Booleano, cuyo valor predeterminado es FALSE. Fuerza a la operación de escritura a bloquear hasta que sea sincronizada con el diario del disco. Si es TRUE, implica una escritura reconocida y sobrescribirá el ajuste "w" a 0.

    Nota: Si se usa esta opción y el registro en el diario está deshabilitado, MongoDB 2.6+ emitirá un error y la escritura fallará; las versiones más antiguas del servidor simplemente ignoran esta opción.

  • "socketTimeoutMS"

    Esta opción especifica el tiempo límite, en milisegundos, para las comunicaciones con socket. Si el servidor no responde en el periodo especificado, se lanzará una MongoCursorTimeoutException y no habrá forma de determinar si el servidor manejó realmente la escritura o no. Se podría especificar un valor de -1 para bloquear indefinidamente. El valor predeterminado para MongoClient es 30000 (30 segundos).

  • "w"

    Véase WriteConcerns. El valor predeterminado de MongoClient es 1.

  • "wTimeoutMS"

    Esta opción especifica el tiempo límite, en milisegundos, para el reconocimiento de un asunto de escritura. Solamente es aplicable cuando "w" sea mayor que 1, ya que el tiempo de espera está relacionado con la replecación. Si el asunto de escritura no se satisface dentro del tiempo límite, se lanzará una MongoCursorException. Se puede especificar un valor de 0 para bloquear indefinidamente. El valor predeterminado es 10000 (diez segundos).

Las siguientes opciones están obsoletas y no deberían usarse más:

  • "safe"

    Obsoleto. Use la opción w de los asuntos de escritura.

  • "timeout"

    Alias obsoleto de "socketTimeoutMS".

  • "wtimeout"

    Alias obsoleto de "wTimeoutMS".

Valores devueltos

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().

Errores/Excepciones

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 límite del lado del cliente. La operación en MongoCollection::$wtimeout es milisegundos.

Historial de cambios

Versión Descripción
1.5.0

se añadió la opción "wTimeoutMS", la cual remplaza a "wtimeout". Emite un error de nivel E_DEPRECATED cuando se usa "wtimeout".

Se añadió la opción "socketTimeoutMS", la cual remplza a "timeout". Emite un error de nivel E_DEPRECATED cuando se usa "timeout".

Emite un error de nivel E_DEPRECATED al usar "safe".

1.3.4 Se añadió la opción "wtimeout".
1.3.0

Se añadió la opción "w".

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.

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 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)
);

?>

Ver también

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


MongoCollection
PHP Manual