La connexion à MongoDB est aussi simple que cela : new Mongo, mais il existe aussi plusieurs options et plusieurs configurations. La page sur la méthode Mongo::__construct() couvre toutes les options offertes par l'API, mais aussi, propose plusieurs cas pratiques.
Si MongoDB est en fonctionnement avec l'option --auth ou avec l'option --keyFile, vous devez vous connecter avant de faire une quelconque opération avec le driver. Vous pouvez vous identifier sur la connexion en fournissant le nom d'utilisateur et son mot de passe directement dans l'URI de connexion :
<?php
$m = new Mongo("mongodb://${username}:${password}@localhost");
?>
Si la connexion à la base de données est interrompue, le driver tentera automatiquement de se re-connecter et de vous ré-identifier.
Vous pouvez aussi vous identifier au niveau de chaque base de données avec la fonction MongoDB::authenticate() :
<?php
$m = new Mongo();
$db = $m->admin;
$db->authenticate($username, $password);
?>
Il y a un inconvénient majeur à cette méthode : si la connexion est interrompue puis, rétablie, la nouvelle connexion ne sera plus authentifiée. Si vous utilisez le format URI, le driver PHP authentifiera automatiquement l'utilisateur lorsqu'une nouvelle connexion est créée.
Pour s'authentifier sur une base de données différente, vous devez spécifier le nom de la base de données après l'hôte. Cet exemple identifiera l'utilisateur dans la base de données "blog" :
<?php
$m = new Mongo("mongodb://${username}:${password}@localhost/blog");
?>
Pour se connecter à une paire de réplication, vous devez spécifier au moins un membre de la paire et utiliser l'option replicaSet.
<?php
$m = new Mongo("mongodb://localhost:27017", array("replicaSet" => "myReplSetName"));
?>
Les versions 1.0.9+ du pilote sont requises pour connecter une paire (les versions d'avant ne detectent pas correctement le maitre et ne se reconnectent pas correctement.
Le pilote PHP requêtera le(s) serveur(s) de base de données listé(s) pour vérifier qui est le maître. Dès qu'il peut se connecter à au moins un hôte listé, et trouver un maitre, la connexion sera réussie. Dans le cas contraire, une MongoConnectionException est envoyée.
Si le maître devient indisponible, les esclaves ne deviendront pas maîtres pendant ces quelques secondes. Pendant ce temps là, la connexion ne sera pas capable d'effectuer les opérations sur la base de données (les connexions aux esclaves pourront toujours effectuer des lectures) et une exception sera levée.
Une fois le maître trouvé, essayer des lectures ou écritures permettra au pilote de détecter le nouveau maître. Le pilote en fera alors sa connexion principale et continuera les opérations normalement.
Pour plus d'informations sur les paires de réplication, reportez-vous à la » documentation interne.
Si vous utilisez MongoDB localement et que vous avez une version 1.0.9 ou supérieure du pilote, vous pouvez vous connecter au travers d'un fichier. MongoDB ouvre automatiquement un fichier de socket au démarrage: /tmp/mongodb-<port>.sock.
Pour vous connecter au fichier de socket, specifiez le chemin dans la chaine de connexion MongoDB:
<?php
$m = new Mongo("mongodb:///tmp/mongo-27017.sock");
?>
Si vous voulez utiliser une authentification sur la connexion avec un fichier de socket, vous devez alors préciser un port égal à 0 comme cela l'analyseur sait où trouver la fin de la chaine de connexion.
<?php
$m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
?>
La création de connexions est une des actions les plus lourdes réalisées par le driver. Cela peut prendre plusieurs millisecondes pour définir correctement une connexion, y compris sur un réseau rapide. Aussi, le driver tente de minimiser le nombre de nouvelles connexions créées en réutilisant les connexions depuis la file d'attente.
Lorsqu'un utilisateur crée une nouvelle instance de la clase Mongo, toutes les connexions nécessaires seront prises depuis leurs files d'attente (les connexions pour le jeu de réplication peuvent nécessiter plusieurs connexions, une pour chaque membre du jeu). Lorsque l'instance de la classe Mongo sort du scope, les connexions seront remises dans la file d'attente. Lorsque le processus PHP existe, toutes les connexions de la file d'attente seront fermées.
La file d'attente de connexions peut générer un nombre important de connexions. Ceci est voulu, et, en utilisant un peu d'arithmétique, vous pouvez trouver le nombre de connexions qui sera créée. Il y a 3 facteurs qui affectent le nombre de connexions :
connections_per_pool
Chaque file d'attente de connexions, créera, par défaut, un nombre illimité de connexions. Cela peut poser quelques soucis : si la file peut créer un nombre illimité de connexions, peut-elle en créer des centaines et ainsi, dépasser les descripteurs de fichiers du serveur ? En pratique, ceci est peu probable, sachant que chaque connexion inutilisée est replacée dans la file d'attente pour une réutilisation ultérieure, aussi, les futures connexions utiliseront la même connexion au lieu d'en créer une nouvelle. Sauf si vous créez volontairement des milliers de connexions à la fois sans les laisser sortir du scope, le nombre de connexions ouvertes devrait rester à un niveau raisonnable.
Vous pouvez voir le nombre de connexions présentes dans la file d'attente en utilisant la méthode MongoPool::info(). Ajouter les champs "in use" et "in pool" pour un serveur donné. Ce sera le nombre total de connexions pour cette file d'attente.
pools_per_process
Chaque adresse de serveur MongoDB sur lequel vous vous connectez utilise sa propre file d'attente de connexions. Par exemple, si votre nom d'hôte local est "example.net", une connexion à "example.net:27017", "localhost:27017", et "/tmp/mongodb-27017.sock" créera 3 files d'attente de connexions. Vous pouvez voir le nombre de files d'attentes de connexions ouvertes en utilisant la méthode MongoPool::info().
processes
Chaque processus PHP a un jeu de files d'attente séparées. PHP-FPM et Apache créent généralement entre 6 et une douzaine de fils. Vérifiez votre configuration pour voir le nombre maximal de processus PHP pouvant être engendrés.
Si vous utilisez PHP-FPM, le fait d'estimer le nombre de connexions peut être délicat car le processus va engendrer encore plus de fils à forte charge. Pour rester dans un contexte sécurisé, regardez le paramètre max_children et ajoutez-y spare_servers+start_servers (choisissez le nombre le plus important). Le résultat sera le nombre de processus PHP (et donc, le nombre de jeux de files d'attente) dont vous pourrez vous attendre.
Les trois variables ci-dessus peuvent être multipliés ensemble pour fournir le nombre maximal de connexions attendues : connections_per_pool*pools_per_process*processes. Notez que connections_per_pool peut être différent suivant les files d'attente, aussi, connections_per_pool devrait être le maximal.
Par exemple, supposez que vous avez 30 connexions par files d'attentes, 10 files d'attente par processus PHP, et 128 processus PHP. Alors, vous pouvez vous attendre à 38400 connexions depuis cette machine. Aussi, vous devriez définir la limite des descripteurs de fichiers de cette machine à une valeur suffisante pour gérer toutes ces connexions, ou alors les descripteurs de fichiers ne seront pas suffisants.
Voir la méthode MongoPool pour plus d'informations sur les files d'attente de connexions.
Note:
Cette section n'est pas pertinente pour les versions 1.2.0+. En 1.2.0+, les connexions sont toujours persistantes et gérées automatiquement par le driver. Voir la méthode MongoPool pour plus d'informations sur les files d'attente de connexions.
La création de nouvelles connexions à la base de données est une opération lente. Pour minimiser le nombre de connexions que vous devez effectuer, vous pouvez utiliser les connexions dites "persistantes". Une connexion persistante est sauvegardée par PHP, et ainsi, vous pourrez utiliser la même connexion pour toutes vos requêtes.
Par exemple, ce programme simple se connecte à la base de données 1000 fois :
<?php
for ($i=0; $i<1000; $i++) {
$m = new Mongo();
}
?>
Son exécution prend approximativement 18 secondes. Si vous changez ce code pour utiliser les connexions persistantes :
<?php
for ($i=0; $i<1000; $i++) {
$m = new Mongo("localhost:27017", array("persist" => "x"));
}
?>
... il ne prend plus que .02 secondes, vu qu'il ne réalise réellement qu'une seule connexion à la base de données.
Les connexions persistantes ont besoin d'une chaîne d'identification (qui est "x" dans notre précédent exemple) afin de les identifier de façon unique. Afin d'utiliser une connexion persistante, le nom de l'hôte, le port, la chaîne d'identification, le nom d'utilisateur ainsi que le mot de passe (si fourni) doivent correspondre avec une connexion persistante existante. Sinon, une nouvelle connexion sera créée avec ces informations d'identification.
Les connexions persistantes sont hautement recommandées et devraient être systématiquement utilisées en production sauf si une très bonne raison indique le contraire. La plupart des raisons qui font qu'elles ne sont pas recommandées dans le cas des bases de données relationnelles ne sont pas applicables pour MongoDB.