(PECL mongo >=0.9.0)
MongoCollection::insert — Insère un tableau dans la collection
$a
[, array $options = array()
] )Toutes les chaînes envoyées à la base de données doivent être en UTF-8. Si une chaîne n'est pas UTF-8, une exception MongoException sera émise. Pour insérer (ou chercher) une chaîne non-UTF-8, utilisez la méthode MongoBinData.
a
Un tableau.
options
Options d'insertion.
"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.
Si le paramètre safe a été défini, retourne un tableau
contenant le statut de l'insertion. Sinon, retourne un booléen indiquant si
le tableau est non vide (un tableau vide ne peut être inséré).
Si un tableau est retourné, les clés suivantes peuvent être présentes :
ok
Doit toujours valoir 1 (à moins que last_error échoue).
err
Si ce champ est non-nul, une erreur est survenue lors de la dernière opération. Si ce champ est défini, il sera une chaîne de caractères décrivant l'erreur survenue.
code
Si une erreur de base de données est survenue, le code erreur de cette erreur sera passé au client.
errmsg
Ce champ est défini si quelque chose a échoué avec une commande de base de données. Il est couplé avec ok qui vaudra alors 0. Par exemple, si w est défini et que le délai maximal d'attente est atteint, errmsg sera défini à "timed out waiting for slaves" et ok vaudra 0. Si ce champ est défini, il sera une chaîne de caractères décrivant l'erreur survenue.
n
Si la dernière opération était une insertion, une mise à jour ou une suppression, le nombre d'objets affectés sera retourné.
wtimeout
Si l'option précédente a expiré en attendant la réplication.
waited
Le temps que l'opération doit attendre avant d'expirer.
wtime
Si w a été défini et que l'opération réussit, ce sera le temps prit pour la réplication vers les w serveurs.
upserted
Si un upsert survient, ce champ contiendra le champ _id du nouvel enregistrement. Pour les upserts, soit ce champ, soit le champ updatedExisting sera présent (à moins qu'une erreur ne survienne).
updatedExisting
Si un upsert met à jour un élément existant, ce champ vaudra TRUE.
Pour les upserts, soit ce champ, soit le champ upserted sera présent
(à moins qu'une erreur ne survienne).
Lance une exception MongoCursorTimeoutException si l'option "safe" est définie et que l'insertion échoue. (Version 1.0.1+)
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.
| Version | Description |
|---|---|
| 1.0.5 | Modification du second paramètre en un tableau d'options. Avant la version 1.0.5, le second paramètre était un booléen indiquant 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 changé. C'est maintenant un tableau contenant les informations d'erreur si l'option "safe" est utilisée, sinon, c'est 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 une insertion sécurisée.
A la place, ceci doit maintenant être effectué via
array('safe' => true).
|
Exemple #1 Exemple avec MongoCollection::insert()
L'insertion d'un objet ajoutera un champ _id sauf s'il est passé par référence.
<?php
$m = new Mongo();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
$a = array('x' => 12);
$collection->insert($a);
var_dump($a);
$b = array('x' => 12);
$ref = &$b;
$collection->insert($ref);
var_dump($ref);
?>
L'exemple ci-dessus va afficher quelque chose de similaire à :
array(2) {
["x"]=>
int(12)
["_id"]=>
object(MongoId)#4 (0) {
}
}
array(12) {
["x"]=>
int(1)
}
Exemple #2 Exemple avec MongoCollection::insert() en mode sécurisé
Cet exemple montre l'insertion de 2 éléments avec le même _id,
ce qui entraine l'émission d'une exception
MongoCursorException vu que le paramètre
safe a été défini.
<?php
$person = array("name" => "Joe", "age" => 20);
$collection->insert($person, true);
// Maintenant, $person a un champ _id, aussi, si vous le sauvegardez à nouveau,
// une exception sera émise
try {
$collection->insert($person, true);
} catch(MongoCursorException $e) {
echo "Vous ne pouvez pas sauvegarder la même personne 2 fois !\n";
}
?>