(PECL mongoclient >=0.9.0)
MongoClient::__construct — Crea un nuevo objeto de conexión a base de datos
$server = "mongodb://localhost:27017"
[, array $options = array("connect" => TRUE)
]] )Si no se proporció ninúng parámetro, se conectará a "localhost:27017" (o lo que fuera especificado en php.ini para mongo.default_host y mongo.default_port).
server debería tener la forma:
mongodb://[nombre_usuario:contraseña@]host1[:puerto1][,host2[:puerto2:],...]/bd
La cadena de conexión siempre comienza con mongodb://, para indicar que es una cadena de conexión con esta forma.
Si se especifican nombre_usuario y contraseña, el constructor intenrará autenticar la conexión con la base de datos antes de devolver. El nombre de usuario y la contraseña son opcionales y deben estar seguidos por un @, si se especifican.
Se debe proporcionar al menos un host (el puerto es opcional, cuyo valor predeterminado siempre es 27017) yand as many hosts as desired may be connected to. Los nombres de host están separados por comas; el constructor devolverá con éxito si se conectó a, al menos, un host. Si no se pudo conectar a ninguno, lanzará una excepción de tipo MongoConnectionException.
Si se especifica un nombre de usuario y una contraseña, se podría especificar una base de datos a la que autenticarse. Si bd no se especifica, se usará "admin".
Se puede usar una cadena de conexión opcional para especificar opciones extra. Las mismas
opciones también son admitidas a través del array options,
y, por lo tanto, están descritas allí.
Una parte de las opciones gobierna la forma en la que el controlador lee desde nodos secundarios en un entorno de conjunto de réplica. Hay disponible también información extra de cómo funcionan las preferencias de lectura en la página de la documentación de preferencias de lectura.
server
El nombre del servidor.
options
Un array con opciones para la conexión. Las opciones disponibles actualmente son:
"connect"
Si el constructor debería conectar antes de devolver. El valor predeterminado es
TRUE. Si se establece a FALSE, el controlador se conectará
automáticamente al servidor cuando
sea necesario realizar una consulta. Alternativamente, se puede ejecutar
MongoClient::connect() de forma manual.
Esta opción no está admitida a través de la cadena de conexión.
"db"
La base de datos en la que autenticarse se puede especificar aquí, en lugar de incluirla en la lista de hosts. Esto anula una base de datos proporcionada en la lista de hosts.
"password"
La contraseña se puede especificar aquí, en lugar de hacerlo en la lista de hosts. Esto es especialmente útil si una contraseña contuviera un carácter "@". Esto anula a una contraseña establecida en la lista de hosts.
"readPreference"
Especifica el tipo de preferencia de lectura. Las preferencias de lectura proporcionan control sobre los secundarios desde los que se pueden leer datos.
Los valores permitidos son: MongoClient::RP_PRIMARY,
MongoClient::RP_PRIMARY_PREFERRED,
MongoClient::RP_SECONDARY,
MongoClient::RP_SECONDARY_PREFERRED y
MongoClient::RP_NEAREST.
Véase la documentación sobre preferencias de lectura para más información.
"readPreferenceTags"
Especifica las etiquetas de preferencia de lectura como un array de strings. Las etiquetas se pueden usar junto con la opción readPreference para un control mayor sobre los secundarios desde los que se podrían leer datos.
Véase la documentación sobre preferencias de lectura para más información.
"replicaSet"
El nombre del conjunto de réplica al que conectarse. Si se proporciona, el primario será automáticamente determinado. Esto significa que el controlador podría acabar por conectarse a un servidor que no estuviera en la lista. Véase el ejemplo del conjunto de réplica abajo para mas detalles.
"timeout"
Durante cúanto tiempo debería el controlador intentar la conexión a la base de datos (en milisegundos).
"username"
El nombre de usuario se puede especificar aquí, en lugar de incluirlo en la lista de hosts. Esto es especialmente útil de un nombre de usuario contuviera un carácter ":". Esto anula un nombre de usuario establecido en la lista de hosts.
"w"
La opción w especifica el Asunto de Escritura para el controlador, que determina por cuánto tiempo éste bloqueará al escribir. El valor predeterminado es 1.
Esta opción es aplicable al conectar tanto a servidores únicos como a conjuntos de réplica. Un valor positivo controla cuántos nodos deberán reconocer la instrucción de escritura antes de que el controlador continue. Un valor de 1 requerirá que el servidor único o primario (en un conjunto de réplica) reconozca la operación de escritura. Un valor de 3 hará que el controlador bloquee hasta que la escritura haya sido aplicada al servidor primario y a dos secundarios (en un conjunto de réplica).
Se usa un valor de tipo string para controlar qué conjuntos de etiquetas se toman en cuenta para asuntos de escritura. "majority" es especial y se asegura de que la opración de escritura haya sido replicada a la mayoría (más del 50%) de los nodos participantes.
"wTimeout"
Esta opción se usa junto con la opción "w". Controla cúantos milisegundos debe esperar el servidor para que se satisfaga el asunto de escritura. Si toma más tiempo, el servidor enviará un señal al controlador comunicando que ha tomado demasiado tiempo, y el controlador lanzará una excepción de tipo MongoCursorException.
Devuelve un nuevo objeto de conexión a bases de datos.
Lanza una MongoConnectionException si falla al intentar conectarse a la base de datos para todos los nombres de host dados. También lanzará una MongoConnnectionException si se proporciona un nombre de usuario o contraseña no válidos. Véase la documentación de MongoConnectionException para excepciones comunes y sus causas.
| Versión | Descripción |
|---|---|
| 1.3.0 |
Se añadieron las opciones "readPreference", "readPreferenceTags", "w" y "wTimeout". |
| 1.2.0 |
Se añadieron las opciones "username" y "password". Eliminada la opción "persist", ya que ahora todas las conexiones son persistentes. Aún se puede usar, pero no afecta a nada.
La opción "replicaSet" ahora toma un string, no un booleano. |
| 1.0.9 | Se añadió la opción "replicaSet". |
| 1.0.2 |
Se cambió el constructor para que tome un array de opciones. Antes de la versión 1.0.2, el constructor tomaba los siguientes parámetros:
|
Ejemplo #1 Ejemplo de conjunto de réplica con MongoClient::__construct()
Este ejemplo muestra cómo el controlador se conecta a un conjunto de réplica. Se asume que hay un conjunto con tres servidores: sf1.example.com, sf2.example.com, y ny1.example.com. El primario podría ser cualquiera de ellos.
<?php
// pasar una lista separada por comas con los nombres de los servidores al constructor
$m1 = new MongoClient("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "miConjuntoRépilca"));
// solamente es necesario pasar una única semilla, el controlador derivará la lista comleta y
// buscará el primario a partir de dicha semilla
$m2 = new MongoClient("mongodb://ny1.example.com", array("replicaSet" => "miConjuntoRépilca"));
?>
Si el primario principal falla, el controlador resolverá qué servidor secundario se convertirá en el nuevo primario y empezará a usar automáticamente esa conexión. La tolerancia a fallos no funcionará correctamente si no se especifica el conjunto de réplica dado por replicaSet.
Al menos una semilla de la lista debe estar funcionando para que el controlador pueda conectarse al conjunto de réplica.
Si se incluyen semillas de dos conjuntos de réplicas distintos, el comportamiento será indefinido.
Véase la » documentación principal sobre conjuntos de réplica para más información.
Ejemplo #2 Conectarse a un socket de dominio
En la versión 1.0.9+, se puede usar un socket de dominio UNIX para conectarse a una instancia de MongoDB que se ejecute localmente. Esto debería ser ligeramente más rápido que utilizar una conexión de red.
En la versión 1.5.0, el servidor de MongoDB abre automáticamente un socket en /tmp/mongodb-<puerto>.sock. Se puede conectar a este socket especificado la ruta en la cadena de conexión:
<?php
// Servidor de MongoDB ejecutándose localmente en el puerto 20000
$m = new MongoClient("mongodb:///tmp/mongodb-20000.sock");
?>
Se puede combinar esto con cualquier otra conexión:
<?php
// intentar conectarse al socket de dominio, recurrir a la conexión de localhost
$m = new MongoClient("mongodb:///tmp/mongodb-27017.sock,localhost:27017");
?>
Ejemplo #3 Ejemplo de autenticación con MongoClient::__construct()
Debe existir un usuario en la base de datos 'admin' antes de intentar usar la autenticación. Se puede crear uno con la interfaz de línea de comandos de Mongo ejecutando:
> use admin
switched to db admin
> db.addUser("testUser", "testPass");
{
"_id" : ObjectId("4b21272fd9ab21611d19095c"),
"user" : "testUser",
"pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59"
}
>
Después de crear un usuario, en este caso, con nombre "testUser" y contraseña "testPass", se puede crear una conexión autenticada:
<?php
$m = new MongoClient("mongodb://testUser:testPass@localhost");
?>
Ejemplo #4 Ejemplo de preferencia de lectura con MongoClient::__construct()
<?php
// Preferir el servidor más cercano del centro de datos "east"
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
Véase la sección Preferencias de lectura de este manual para más información.