(PECL mongoclient >=0.9.0)
MongoClient::__construct — Crée un nouvel objet de connexion à une base de données
$server = "mongodb://localhost:27017"
[, array $options = array("connect" => TRUE)
]] )Si aucun paramètre n'est passé, la connexion se fera sur "localhost:27017" (ou ce qui a été spécifié dans php.ini pour mongo.default_host et mongo.default_port).
server doit être de la forme :
mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
La chaine de connexion débute toujours par mongodb://.
Si username et password sont précisés, le constructeur tentera d'authentifier la connexion à la base. Username et password sont optionnels et doivent être suivis d'une @, si renseignés.
Au moins un hôte doit être précisé (port optionnel, par défaut 27017) et plusieurs hôtes vers lesquels se connecter peuvent être passés. Les noms d'hôtes sont séparés par des virgules et le constructeur exécutera sans erreur si au moins un des hôtes peut être connecté. Si il ne peut se connecter à aucun hôte, il enverra une MongoConnectionException.
Si vous avez précisé un username et un password, vous devez préciser une base de données envers laquelle s'authentifier. Si db n'est pas renseigné, "admin" sera utilisé.
Une chaîne optionnelle de la requête peut être utilisée pour spécifier
d'autres options. Les mêmes options sont également supportées via le tableau
options, et y sont décrites.
Une partie de ces options concerne la façon dont le driver lit depuis des noeuds secondaires dans un environnement de jeu de réplication. Vous pouvez trouver plus d'informations sur la méthode de fonctionnement des préférences de lecture via la page de la documentation relative aux préférences de lecture.
server
Le nom du serveur.
options
Un tableau d'options pour la connexion. Les options disponibles sont :
"connect"
Si le constructeur doit se connecter avant de retourner l'objet. Par défaut
TRUE. Lorsque vaut FALSE, le driver va
automatiquement se connecter au serveur chaque
fois qu'il est nécessaire d'y faire une requête. Mais vous pouvez aussi
exécuter la méthode MongoClient::connect() manuellement.
Cette option n'est pas supportée via la chaîne de connexion.
"db"
La base de données sur laquelle l'authentification doit s'effectuer ; elle peut être spécifiée ici au lieu de l'inclure dans la liste des hôtes. Ce paramètre écrase une base de données fournie dans la liste des hôtes.
"password"
Le mot de passe peut être spécifié ici, au lieu de l'inclure dans la liste des hôtes. Ceci est utile tout spécialement si le mot de passe contient le caractère "@". Ce paramètre écrase le mot de passe défini dans la liste des hôtes.
"readPreference"
Spécifie le type de préférence de lecture. Les préférences de lecture vous permettent de contrôler quel secondaire sera utilisé pour lire les données.
Les valeurs possibles sont : MongoClient::RP_PRIMARY,
MongoClient::RP_PRIMARY_PREFERRED,
MongoClient::RP_SECONDARY,
MongoClient::RP_SECONDARY_PREFERRED et
MongoClient::RP_NEAREST.
Voir la documentation sur les préférences de lecture pour plus d'informations.
"readPreferenceTags"
Spécifie les tags pour les préférences de lecture. Les tags peuvent être utilisés en combinaison de l'option readPreference afin de contrôler le type de données que l'on doit lire depuis le secondaire.
Voir la documentation sur les préférences de lecture pour plus d'informations.
"replicaSet"
Nom du pool de réplicats sur lequel se connecter. Si fourni, le primaire sera déterminé en utilisant la commande ismaster sur les serveurs, ainsi le pilote peut se connecter à un serveur qui n'était même pas listé. Voyez l'exemple après pour plus de détails.
"timeout"
Délai d'attente maximale de connexion à la base de données (en millisecondes).
"username"
Le nom d'utilisateur peut être spécifié ici, au lieu de l'inclure dans la liste des hôtes. Ceci est utile tout spécialement si le nom d'utilisateur contient un caractère ":". Ce paramètre écrase le nom d'utilisateur défini dans la liste des hôtes.
"w"
L'option w contrôle la durée de blocage du driver lors d'une écriture.La valeur par défaut est 1.
Une valeur entière positive contrôle le nombre de noeuds dans un jeu de réplication qui ont reçu une instruction d'écriture avant que le driver ne continue. Une valeur de 3 signifie que l'écriture a été appliquée au primaire ainsi qu'à deux autres membres du jeu de réplication.
Une chaîne est utilisée pour contrôler quels jeux de tags seront pris en compte pour les écritures. La chaîne "majority" est spéciale et s'assure que les opérations d'écriture ont été appliquées à la majorité (plus de 50%) des noeuds concernés.
"wTimeout"
Cette option est utilisée avec l'option "w". Elle permet de contrôler le nombre de millisecondes d'attente du serveur pour les opérations d'écriture. Si ces opérations prennent plus de temps, alors le serveur le signale au driver et ce dernier lancera une exception de type MongoCursorException.
Retourne un nouvel objet de connexion à la base de données Mongo.
Emet une exception MongoConnectionException si la connexion échoue avec les identifiants pour la base de données considérée ou si les identifiants sont invalides. Voyez la documentation de MongoConnectionException pour en savoir plus sur les exceptions courantes et leurs causes.
| Version | Description |
|---|---|
| 1.3.0 |
Ajout des options "readPreference", "readPreferenceTags", "w" et "wTimeout". |
| 1.2.0 |
Ajout des options "username" et "password". Suppression de l'option "persist", toutes les connexions sont désormais persistantes. Le paramètre peut tout de même être utilisé, il sera simplement ignoré.
Le paramètre "replicaSet" accepte maintenant une chaine, pas un booléen. |
| 1.0.9 | Ajout de l'option "replicaSet". |
| 1.0.2 |
Le constructeur a changé pour accepter une tableau. Avant 1.0.2, le constructeur acceptait les paramètres suivants :
|
Exemple #1 Exemple avec MongoClient::__construct() et un pool de réplicats
Cet exemple montre comment se connecter avec le driver à un pool de réplicats. Il suppose un jeu de trois serveurs : sf1.example.com, sf2.example.com et ny1.example.com. Le primaire peut être l'un de ces serveurs.
<?php
// Passer une liste séparée par une virgule de noms de serveurs au constructeur
$m1 = new MongoClient("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet"));
// Vous ne passez qu'un seul serveur, le pilote récupèrera la liste complète et trouvera
// le primaire depuis ce serveur
$m2 = new MongoClient("mongodb://ny1.example.com", array("replicaSet" => "myReplSet"));
?>
Si le primaire courant échoue, le pilote calculera quel serveur secondaire deviendra le nouveau primaire et utilisera sa connexion. Le failover ne fonctionnera pas correctement si replicaSet n'est pas spécifié.
Au moins un serveur dans la liste doit fonctionner pour que le pilote se connecte au pool de replica.
Si vous incluez des serveurs depuis deux pools de réplicats distincts, le comportement est alors indéfini.
Voyez la » documentation du coeur sur la réplication.
Exemple #2 Connexion via socket UNIX
Dans les versions 1.0.9+, vous pouvez utiliser un socket du domaine UNIX pour vous connecter à une instance de MongoDB locale. Ceci devrait être plus rapide qu'une connexion réseau.
Dans la version 1.5.0, Le serveur MongoDB ouvre automatiquement un socket à /tmp/mongodb-<port>.sock. Vous pouvez vous y connecter en précisant le chemin dans la chaine de connexion :
<?php
// Serveur MongoDB local sur le port 20000
$m = new MongoClient("mongodb:///tmp/mongodb-20000.sock");
?>
Vous pouvez combiner cela avec d'autres connexions:
<?php
// Essaye la connexion socket UNIX, utilise localhost sinon
$m = new MongoClient("mongodb:///tmp/mongodb-27017.sock,localhost:27017");
?>
Exemple #3 Exemple d'authentification MongoClient::__construct()
Un utilisateur doit exister dans la base de données admin avant de lancer l'authentification. Vous pouvez créer un utilisateur avec la commande shell Mongo suivante :
> use admin
switched to db admin
> db.addUser("testUser", "testPass");
{
"_id" : ObjectId("4b21272fd9ab21611d19095c"),
"user" : "testUser",
"pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59"
}
>
Après avoir crée un utilisateur, dans notre cas de nom "testUser" et password "testPass", vous pouvez créer une connexion authentifiée :
<?php
$m = new MongoClient("mongodb://testUser:testPass@localhost");
?>
Exemple #4 Exemple avec MongoClient::__construct() et des préférences de lecture
<?php
// Préfère le serveur le plus proche dans le centre de données "east"
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
Voir la section relative aux préférences de lecture de ce manuel pour plus d'informations.