(mongodb >=1.0.0)
MongoDB\Driver\Manager::executeCommand — Exécute une commande de base de données
$db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor
Sélectionne un serveur en fonction de l'option "readPreference"
et exécute la commande sur ce serveur.
Cette méthode n'applique aucune logique spéciale à la commande. Les valeurs
par défaut des options "readPreference",
"readConcern" et "writeConcern" seront
déduites à partir d'une transaction active (indiquée par l'option
"session"). S'il n'y a pas de transaction active, une
préférence de lecture primaire sera utilisée pour la sélection du serveur.
Les valeurs par défaut ne seront pas déduites à partir de l'URI de connexion. Il est donc recommandé aux utilisateurs d'utiliser des méthodes de commande de lecture et/ou d'écriture spécifiques si possible.
db (string)Le nom de la base de données sur laquelle la commande sera exécutée.
command (MongoDB\Driver\Command)La commande à exécuter.
options
| Option | Type | Description |
|---|---|---|
| readConcern | MongoDB\Driver\ReadConcern |
Une préoccupation de lecture à appliquer à l'opération. Cette option est disponible dans MongoDB 3.2+ et se traduira par une exception au moment de l'exécution si elle est spécifiée pour une version plus ancienne du serveur. |
| readPreference | MongoDB\Driver\ReadPreference |
Une préférence de lecture à utiliser pour sélectionner un serveur pour l'opération. |
| session | MongoDB\Driver\Session |
Une session à associer à l'opération. |
| writeConcern | MongoDB\Driver\WriteConcern |
Une préoccupation d'écriture à appliquer à l'opération. |
Si vous utilisez une "session" qui a une transaction
en cours, vous ne pouvez pas spécifier l'option "readConcern"
ou "writeConcern". Tenter de faire ceci lancera une exception
MongoDB\Driver\Exception\InvalidArgumentException.
À la place vous devriez définir ces options quand vous créez la transaction avec
MongoDB\Driver\Session::startTransaction().
Retourne un MongoDB\Driver\Cursor en cas de succès.
"session" option is used with an associated transaction in combination with a "readConcern" or "writeConcern" option."session" est utilisée conjointement avec une préoccupation d'écriture non reconnu.
| Version | Description |
|---|---|
| PECL mongodb 2.0.0 |
Le paramètre options n'accepte plus
une instance de MongoDB\Driver\ReadPreference.
|
| PECL mongodb 1.21.0 |
Passer un objet MongoDB\Driver\ReadPreference en tant
qu'options est obsolète et sera supprimé dans la 2.0.
|
| PECL mongodb 1.4.4 |
Une MongoDB\Driver\Exception\InvalidArgumentException
sera lancée si l'option "session" est utilisée en
combinaison avec une préférence d'écriture non reconnue.
|
| PECL mongodb 1.4.0 |
Ce troisième paramètre est maintenant un tableau d'options.
Pour des raisons de compatibilité ascendante, ce paramètre acceptera
toujours un objet MongoDB\Driver\ReadPreference.
|
Exemple #1 MongoDB\Driver\Manager::executeCommand() avec une commande retournant un seul document de résultat
<?php
$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$command = new MongoDB\Driver\Command(['ping' => 1]);
try {
$cursor = $manager->executeCommand('admin', $command);
} catch(MongoDB\Driver\Exception $e) {
echo $e->getMessage(), "\n";
exit;
}
/* La commande ping retourne un seul document de résultat, nous devons donc
* accéder au premier résultat dans le curseur. */
$response = $cursor->toArray()[0];
var_dump($response);
?>L'exemple ci-dessus va afficher :
array(1) {
["ok"]=>
float(1)
}
Exemple #2 MongoDB\Driver\Manager::executeCommand() avec une commande retournant un curseur
<?php
$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1, 'y' => 'foo']);
$bulk->insert(['x' => 2, 'y' => 'bar']);
$bulk->insert(['x' => 3, 'y' => 'bar']);
$manager->executeBulkWrite('db.collection', $bulk);
$command = new MongoDB\Driver\Command([
'aggregate' => 'collection',
'pipeline' => [
['$group' => ['_id' => '$y', 'sum' => ['$sum' => '$x']]],
],
'cursor' => new stdClass,
]);
$cursor = $manager->executeCommand('db', $command);
/* La commande d'agrégation peut éventuellement retourner ses résultats dans
* un curseur au lieu d'un seul document de résultat. Dans ce cas, nous pouvons
* itérer directement sur le curseur pour accéder à ces résultats. */
foreach ($cursor as $document) {
var_dump($document);
}
?>L'exemple ci-dessus va afficher :
object(stdClass)#6 (2) {
["_id"]=>
string(3) "bar"
["sum"]=>
int(10)
}
object(stdClass)#7 (2) {
["_id"]=>
string(3) "foo"
["sum"]=>
int(2)
}
Exemple #3 Limiter le temps d'exécution d'une commande
Le temps d'exécution d'une commande peut être limité en spécifiant une
valeur pour "maxTimeMS" dans le document
MongoDB\Driver\Command. Il est à noter que cette limite de
temps est appliquée côté serveur et ne prend pas en compte la latence du
réseau. Voir
» Terminer les opérations en cours
dans le manuel MongoDB pour plus d'informations.
<?php
$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$command = new MongoDB\Driver\Command([
'count' => 'collection',
'query' => ['x' => ['$gt' => 1]],
'maxTimeMS' => 1000,
]);
$cursor = $manager->executeCommand('db', $command);
var_dump($cursor->toArray()[0]);
?>Si la commande ne parvient pas à se terminer après une seconde d'exécution sur le serveur, une MongoDB\Driver\Exception\ExecutionTimeoutException sera lancée.
Note: Si un deuxième
readPreferenceest utilisé, il est de la responsabilité de l'appelant de s'assurer que lacommandepeut être exécutée sur un secondaire. Aucune validation n'est effectuée par le pilote.
Note: Cette méthode n'utilise pas par défaut la préférence de lecture de l'URI de connexion MongoDB. Les applications qui en ont besoin devraient envisager d'utiliser MongoDB\Driver\Manager::executeReadCommand().