[edit] Last updated: Fri, 25 May 2012

MongoCollection::update

(PECL mongo >=0.9.0)

MongoCollection::update — Modifie les enregistrements

Description

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

Liste de paramètres

criteria

La description des objets à modifier.

new_object

L'objet avec lequel modifier les objets trouvés.

options

Ce paramètre est un tableau associatif sous la forme array("optionname" => <boolean>, ...). Les options actuellement supportées sont :

"upsert"

Si aucun document ne correspond au critère $criteria, un nouveau document sera créé depuis les variables $criteria et $new_object (voir l'exemple avec upsert ci-dessous).
"multiple"

Tous les documents correspondants au $criteria seront mis à jour. MongoCollection::update() a le comportement opposé de MongoCollection::remove(): elle met à jour un document par défaut, pas tous les documents correspondants. Il est recommandé de toujours précisez si vous voulez mettre à jour un document ou plusieurs, la base de données pouvant changer son comportement par défaut dans le futur.
"safe"

Peut être un booléen ou un entier, et vaut par défaut FALSE. Si vaut FALSE, le programme continue l'exécution sans attendre la réponse de la base de données. Si vaut TRUE, le programme attendra la réponse de la base de données et lancera une exception MongoCursorException si l'insertion a échouée.

Si vous utilisez la réplication et que le maitre a changé, utiliser "safe" fera que le pilote se déconnectera du maitre, enverra une exception, et tentera de trouver un nouveau maitre à l'opération suivante (votre application doit décider si oui ou non l'opération devra être rééssayée sur le nouveau maitre).

Si vous n'utilisez pas "safe" avec une paire de réplication et que le maitre change, il n'y aura aucun moyen pour le pilote d'avoir connaissance de ce changement et il continuera des écritures en échec.

Si safe est un entier, l'insertion sera répliquée sur l'ensemble des machines avant de retourner le succès de l'opération (ou lancera une exception si la réplication échoue). Cette valeur écrase la variable w définie sur la collection.
"fsync"

Booléen et vaut par défaut FALSE. Force l'insertion à être synchronisée sur le disque avant de retourner le succès de l'opération. Si vaut TRUE, une insertion sécurisée sera effectuée et le paramétrage de safe sera automatiquement valorisé à FALSE.
"timeout"

Entier, par défaut, vaut MongoCursor::$timeout. Si "safe" est défini, il définira (en millisecondes) le temps d'attente du client d'une réponse de la base de données. Si la base de données ne répond pas dans la période de timeout, une exception MongoCursorTimeoutException sera émise.

Valeurs de retour

Si le paramètre safe a été défini, retourne un tableau contenant le statut de la mise à jour. Sinon, retourne un booléen représentant le fait que le tableau n'était pas vide (un tableau vide ne sera pas inséré). Ce champ de ce tableau est décrit dans la documentation de la méthode MongoCollection::insert().

Erreurs / Exceptions

Lance une exception MongoCursorException si l'option "safe" est définie et que la mise à jour échoue.

Lance une exception MongoCursorTimeoutException si l'option "safe" est définie et que l'opération prend plus de temps que MongoCollection::$wtimeout millisecondes. Ceci ne tue pas le processus serveur, mais uniquement le délai d'attente côté client.

Historique

Version	Description
1.0.1	Le paramètre "options" passe de booléen à un tableau. En version Pre-1.0.1, le second paramètre était une valeur booléenne optionnelle, spécifiant un upsert.
1.0.5	Ajout de l'option "safe".
1.0.9	Ajout de la possibilité de passer des entiers à l'option "safe" (auparavant, seuls les booléens étaient acceptés) et ajout de l'option "fsync".
1.0.9	Le type retourné a été modifié en un tableau contenant les informations de l'erreur si l'option "safe" est utilisé, sinon, ce sera un booléen comme auparavant.
1.0.11	Se déconnecte lors d'erreurs "not master" si "safe" est utilisé.
1.2.0	Ajout de l'option timeout.
1.3.0	Le paramètre `options` n'accepte plus de booléen pour indiquer un upsert. A la place, ceci doit être effectué via array('upsert' => true).

Exemples

Exemple #1 Exemple avec MongoCollection::update()

Ajout d'un champ adresse à un document.


<?php

$c->insert(array("firstname" => "Bob", "lastname" => "Jones" ));
$newdata = array('$set' => array("address" => "1 Smith Lane"));
$c->update(array("firstname" => "Bob"), $newdata);

var_dump($c->findOne(array("firstname" => "Bob")));

?>

L'exemple ci-dessus va afficher quelque chose de similaire à :

array(4) {
  ["_id"]=>
  object(MongoId)#6 (0) {
  }
  ["firstname"]=>
  string(3) "Bob"
  ["lastname"]=>
  string(5) "Jones"
  ["address"]=>
  string(12) "1 Smith Lane"
}

Exemple #2 Exemple avec MongoCollection::update() et upsert

Les Upserts permettent de simplifier le code, vu qu'une simple ligne permet de créer l'objet s'il n'existe pas encore, et de le mettre à jour s'il existe.


<?php

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

?>

L'exemple ci-dessus va afficher quelque chose de similaire à :

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

Si $new_object ne se compose pas d'opérateurs à $, un upsert créera un nouveau document composé uniquement des champs fournis. Ceci adopte le comportement d'une mise à jour normale, dans laquelle ne pas utiliser d'opérateurs $ implique que tout le document soit écrasé.


<?php

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

?>

L'exemple ci-dessus va afficher quelque chose de similaire à :

array(3) {
  ["_id"]=>
  object(MongoId)#10 (0) {
  }
  ["username"]=>
  string(6) "joe312"
  ["createdAt"]=>
  object(MongoDate)#4 (0) {
  }
}

Exemple #3 Exemple avec plusieurs MongoCollection::update()

Par défaut, MongoCollection::update() met uniquement à jour le premier document correspondant aux critères $criteria qu'il trouve. En utilisant l'option "multiple", ce comportement est redéfini.

Cet exemple ajoute un champ "gift" à chaque personne possédant un anniversaire dans le prochain jour.


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

?>

Voir aussi

La documentation PHP sur les mises à jour et la » documentation core de MongoDB.

MongoCollection::validate

MongoCollection::__toString

[edit] Last updated: Fri, 25 May 2012

add a note User Contributed Notes MongoCollection::update

nerds at limeworks dot com dot au 22-Aug-2011 04:39


For anyone referencing records by the Mongo _id object, it's important to recognise that it is in fact an object, and not a string. 



If you have a record with a Mongo ID of say "4e519d5118617e88f27ea8cd" that you are trying to retrieve or update, you cannot search for it using something like:

<?php

$m = new Mongo();

$db = $m->selectDB('db');

$collection = 'collection';

$db->$collection->findOne(array('_id', '4e519d5118617e88f27ea8cd'));

?>



There is some documentation that mentions simple conversion to string will solve this, but I have found the only reliable way to locate records based on their ID is to first pass it to MondoID(), then use that for reference.



Something like this will be far more reliable:

<?php

$m = new Mongo();

$db = $m->selectDB('db');

$collection = 'collection';

$mongoID = new MongoID('4e519d5118617e88f27ea8cd');

$db->$collection->findOne(array('_id', $mongoID));

?>



This may prove useful for anyone using the ID object like an auto-increment database key would be used in MySQL or similar.

joshuadburns at hotmail dot com 08-Nov-2010 01:51


Please note under optional third parameter "options":



While the official MongoDB documentation references the keyword "multi" to flag the use of multiple updates, the PHP implementation uses the key "multiple" instead.



This may cause a little confusion if you're basing your keys on the OFFICIAL MongoDB documentation.

rithish[at]gmail[dot]com 02-Nov-2010 06:22


Do note, for incrementing a value using $inc, typecast the value to an integer before passing the new object to update().





<?php


$votes = (int) $votes;


$newData = array('$inc' => array('votes'=>$votes));


$c->update(array("firstname" => "Bob"), $newData);


?>





This is especially noteworthy, if you are taking values from $_GET and pushing them for increment.

jeff at canuckistani dot ca 17-Sep-2010 05:05


The return type of update changed in 1.09 if you are using safe => TRUE. It now returns something that looks like the info returned by MongoDB::lastError:



Array

(

    [err] => 

    [updatedExisting] => 1

    [n] => 1

    [ok] => 1

)

add a note