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.2.11	Lance une alerte de niveau `E_DEPRECATED` lorsque le paramètre `options` est de type scalar.
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.