MongoClient::__construct

(PECL mongo >=1.3.0)

MongoClient::__construct — Crée un nouvel objet de connexion à une base de données

Description

public MongoClient::__construct ([ string $server = "mongodb://localhost:27017" [, array $options = array("connect" => TRUE) [, array $driver_options ]]] )

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. Veuillez vous reporter à la section sur les jeux de réplication pour plus d'informations sur la façon dont on se connecte aux jeux de réplication.

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. Voir les exemples ci-dessous pour connaitre la façon pour définir ces options.

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.

Liste de paramètres

server

Le nom du serveur.

options

Un tableau d'options pour la connexion. Les options disponibles sont :

"authMechanism"

Les mécanismes disponibles sont :

authMechanism	Description	Disponibilité
MONGODB-CR	Authentification en utilisant le mécanisme Challenge Response. C'est la valeur par défaut.	Toutes les versions MongoDB
MONGODB-X509	Authentification en utilisant les certificats X509	MongoDB 2.6. Uniquement disponible lorsque OpenSSL est activé
PLAIN	Authentification en utilisant un nom d'utilisateur avec un mot de passe en clair. Doit être utilisé sur des connexions SSL. Habituellement utilisé par MongoDB pour s'identifier sur des serveurs LDAP tierces	MongoDB Enterprise 2.4. Le driver doit avoir été compilé avec CyrusSASL2
GSSAPI	Authentification via les systèmes kerberos	MongoDB Enterprise 2.4. Le driver doit avoir été compilé avec CyrusSASL2
SCRAM-SHA-1	Authentification en utilisant SCRAM-SHA-1	MongoDB 3.0.

"authSource"

Doit être défini au nom de la base de données dans laquelle l'utilisateur est défini.
"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.

Avertissement
Cette option n'est pas supportée via la chaîne de connexion.
"connectTimeoutMS"

Durée pendant laquelle une connexion peut rester ouverte avant de se fermer, en millisecondes. Vaut par défaut 60000 (60 secondes).

Si -1 est spécifié, aucun délai maximal d'attente de connexion ne sera appliqué et PHP va utiliser la valeur de default_socket_timeout.
"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.
"fsync"

Lorsque "fsync" est défini, toutes les opérations en écriture seront bloquantes tant que la base de données ne les aura pas écrites sur le disque. Ceci rend les opérations d'écriture plus lentes, mais garantie que les écritures réussissent et que les opérations peuvent être retrouvées dans le cas d'un échec total du système.

Si le serveur MongoDB a son historisation d'activé, cette option est identique à "journal". Si l'historisation n'est pas activée, cette option s'assure que les opérations d'écriture seront synchronisées dans les fichiers de base de données sur le disque.

Note: Si l'historisation est activée, les utilisateurs sont vivement encouragés à utiliser l'option "journal" plutôt que "fsync". N'utilisez pas "fsync" et "journal" en même temps ; cela produirait une erreur.
"journal"

Lorsque "journal" est défini, toutes les opérations en écriture seront bloquantes tant que la base de données n'aura pas reflétée ces modifications dans le journal du disque. Ceci rend les opérations en écriture plus lentes, mais garantie que les écritures ont réussi et que les opérations peuvent être retrouvées en cas d'échec total du système.

Note: Si cette option est utilisée et que l'historisation est activée, MongoDB 2.6+ va émettre une erreur, et l'écriture échouera ; les anciennes versions de serveur vont simplement ignorer cette option.
"gssapiServiceName"

Défini le » service principal Kerberos. Uniquement applicable lorsque authMechanism=GSSAPI. Par défaut, "mongodb".
"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.
"secondaryAcceptableLatencyMS"

Lors d'une lecture depuis un secondaire (en utilisant ReadPreferences), ne pas lire depuis les secondaires dont on sait que la latence dépasse secondaryAcceptableLatencyMS. Par défaut, vaut 15
"socketTimeoutMS"

La durée qu'une opération de socket (lecture ou écriture) peut prendre avant d'atteindre le délai maximal d'attente, en millisecondes. Par défaut, vaut 30000 (30 secondes).

Si -1 est spécifié, les opérations de socket peuvent bloquer indéfiniement. Cette option peut également être définie pour chaque opération en utilisant la méthode MongoCursor::timeout() pour les requêtes, ou l'option "socketTimeoutMS" pour les méthodes d'écriture.

Note: Ceci est un délai d'attente maximal côté client. Si une opération en écriture atteint le délai maximal d'attente, il n'y a aucune façon de savoir si le serveur gère actuellement l'écriture ou non, sachant que l'exception MongoCursorTimeoutException sera émise au lieu de retourner un résultat d'écriture.
"ssl"

Un booléen pour spécifier si l'on souhaite ou non activer SSL pour les connexions MongoDB. Les autres options comme les certificats peuvent être définies avec Options de contexte SSL.
"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.
"wTimeoutMS"

Cette option spécifie la durée limite, en millisecondes, pour une prise en compte de la préoccupation d'écriture. Ceci n'est applicable que pour les opérations en écriture où "w" est supérieur à 1, sachant que le délai d'attente maximal concerne aussi la réplication. Si la préoccupation en écriture n'est pas respectée pendant le temps limite, une exception MongoCursorException sera émise. Une valeur de 0 peut être spécifiée pour bloquer indéfiniement. La valeur par défaut est 10000 (dix secondes).

Les options suivantes sont obsolètes et ne doivent plus être utilisées :

"slaveOkay"

Obsolète. Veuillez utiliser plutôt les options de préférence de lecture.
"timeout"

Alias obsolète pour "connectTimeoutMS".
"wTimeout"

Alias obsolète pour "wTimeoutMS".

driver_options

Un tableau d'options pour le driver MongoDB. Les options incluent les configurations de connexions des options de contexte pour SSL ou les fonctions de rappel de l'identification.

"context"

Le contexte de flux à attacher à toutes les nouvelles connexions. Ceci vous permet, par exemple, de configurer les certificats SSL décrits sur la page de la documentation sur les options de contexte SSL. Voir le tutorial sur la connexion via SSL.

Valeurs de retour

Retourne un nouvel objet de connexion à la base de données Mongo.

Erreurs / Exceptions

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.

Exemples

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.
// Notez que vous n'avez pas besoin de passer tous les membres du jeu de réplication,
// le driver va dériver la liste complète.
$m1 = new MongoClient("mongodb://sf2.example.com,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.

Exemple #5 Exemple avec MongoClient::__construct() et des options

Les options peuvent être passées à la fois directement dans la chaîne de requête dans la connexion, ou comme tableau passé comme second argument du constructeur.

Ici, nous définissons l'option journal à TRUE et readPreference au secondaire préféré, comme défaut pour toutes les opérations en écriture :


<?php
$m = new MongoClient("mongodb://localhost/?journal=true&readPreference=secondary");
?>

Et maintenant, nous faisons la même chose mais via le tableau d'options :


<?php
$options = array(
    'journal' => true,
    'readPreference' => 'secondary',
);
$m = new MongoClient("mongodb://localhost/", $options);
?>

Exemple #6 Exemple avec MongoClient::__construct() et les 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 sur les préférences de lecture de ce manuel pour plus d'informations.

Historique

Version	Description
1.6.0	Ajout du support de `"SCRAM-SHA-1"` pour l'option `"authMechanism"`.
1.5.0	Ajout de `"authMechanism"`, `"gssapiServiceName"` et `"secondaryAcceptableLatencyMS"`.
1.4.0	Ajout de l'option `"ssl"` et du support de la connexion via SSL. Ajout de l'option `"wTimeoutMS"`, qui remplace l'option `"wTimeout"`. Emets une alerte de niveau `E_DEPRECATED` lorsque `"slaveOkay"` ou `"timeout"` est utilisé.
1.5.0	Ajout de `"authSource"`.
1.3.4	Ajout des options `"connectTimeoutMS"` et `"socketTimeoutMS"`.
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é. `"persist"` Si la connexion doit être persistante. La chaine représentant la valeur est utilisée comme identifiant de connexion, ainsi deux instances de MongoClient qui sont initialisées avec `array("persist" => "foobar")` vont partager la même connexion à la base, alors que une instance initialisée avec `array("persist" => "barbaz")` utilisera une connexion différente. 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 : `server` Nom du serveur. `connect` Paramètre optionnel indiquant si le constructeur doit se connecter à la base avant de retourner l'objet. Par défaut `TRUE`. `persistent` Si la connexion doit être persistante. `paired` Si la connexion doit être pairée.

add a note

User Contributed Notes 3 notes

down

mike at eastghost dot com ¶

11 years ago


HOLY MOLY, 100 to 200 times instant speed boost in one small change.

"In version 1.0.9+, you can use a UNIX domain socket to connect to an instance of MongoDB running locally. This should be slightly faster than using a network connection."

is an EXTREME understatement.  Just trying out stuff, playing around, etc., we changed from

MongoClient( 'mongodb://pri.eastghost.com:27017' etc)

to

MongoClient ( 'mongodb:///tmp/mongodb-27017.sock' etc)

and saw instant 100x-200x speed boost, all else untouched.
page times went from 700 - 1400 (as in 1.4 seconds)
to 7 as in milliseconds.

mongo driver 1.4.1
(for apache 2.6)

down

mike at eastghost dot com ¶

9 years ago


FOLLOW UP to comment on speed

Now using --
mongo 3.0.1 pre-compiled binaries
using mongo/php-1.6.6. driver from PECL
on php 5.6.0
on apache 2.4
on debian wheezy 7.8

Dropped in mongo 301 binaries
everything else unchanged
restarted apache

instantly started getting "No candidate servers found"
upgraded to mongo/php-1.6.6 driver on pecl
same result

of these four parms to \MongoClient()

A) 'mongodb:///tmp/mongodb-27017.sock'
B) #'mongodb://127.0.0.1:27017'
C) #'mongodb://localhost:27017'
D) #'mongodb://pri.eastghost.com:27017'

A) used to be 100x to 200x faster than B), C) and maybe 400x faster than D), as explained in comment below, but initially (after mongo 3.0.1 drop-in) A) stopped dead.  Tried B, instantly began working.  Went back to A), kept working.  Almost seems as if driver 1.6.6 can not populate candidate servers list when called via unix socket (/tmp/mongodb-27017.sock), but once the list is populated, calling via unix socket magically works fine.

While screwing around with this, all else unchanged, we're now noticing B) and C) seem to be as fast as A), and D) is only slightly slower (due to connect over WAN, instead of local LAN).  This behavior is as it theoretically should be: Maybe the once huge difference in the mongo php driver between unix sockets and localhost has been fixed?  Still testing -- will report back if any slowdown noticed.

see https://groups.google.com/forum/#!topic/mongodb-user/RTBDDMwywzA

down

mike at eastghost dot com ¶

11 years ago


read somewhere that



$uri  = 'mongodb://rs1.example.com/?w=0';



(the w=0 parm) makes the MongoDB driver accept 'blind writes' without waiting for any confirmation of write success from server.

add a note