(PECL mongo >=1.3.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, y 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. Véase la sección Conjuntos de réplica para información sobre cómo conectarse a Conjuntos de réplica.
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í. Véanse los ejemplo de abajo sobre
como establecer estas opciones.
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.
"connectTimeoutMS"
Cuánto puede tomar una conexión para ser abierta antes de expirar en milisegundos.
"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.
"fsync"
Cuando se establece fsync, todas las operaciones de lectura en la base de datos únicamente devuelvan cuando la escritura haya sido sincronizada con el disco. Esto hace que las operaciones de lectura sean más lentas, pero garantiza que la operación de escritura tenga éxito y se consigne al disco. Si se tiene la opción "journal" activada en MongoDB (lo predeterminado), la sincronización le sucede solamente al journal. Si no está habilitado, el uso de fsync requiere un volcado completo al disco.
No use esta opción, está obsoleta; use la opción journal en su lugar, quizá junto con la opción w.
"journal"
Cuando se establece journal, todas las operaciones de lectura en la base de datos bloquearán hasta que el servidor de bases de datos haya volcado sus ficheros de bases de datos al disco. Esto hace que las operaciones sean marginalmente más lentas, pero garantiza que la operación de escritura tenga éxito y que pueda ser recuperada en caso de un fallo total del sistema.
"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.
"socketTimeoutMS"
Durante cuánto tiempo se puede enviar o recivir desde un socket antes de que expite.
Nota: Es un tiempo de espera del lado del cliente. Si un insert afecta al valor de socketTimeoutMS, no hay manera de conocer si el servidor realmente recibió la escritura.
"ssl"
Un booleano para especificar si se desea habilitar SSL para las conexiones a MongoDB. Las opciones extra, como los certificados, se pueden establecer con Opciones de contexto para SSL.
"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.
"wTimeoutMS"
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.
Las siguientes opciones están obsoletas y no deberían usarse más:
"timeout"
Alias obsoleto de "connectTimeoutMS".
"wTimeout"
Alias obsoleto de "wTimeoutMS".
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.
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
// Observe que no es necesario pasar todos los miembros del conjunto réplica, el controlador
// derivará la lista completa.
$m1 = new MongoClient("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet"));
?>
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.
Ejemplo #5 Ejemplo de opciones de MongoClient::__construct()
Las opciones puede pasarse a través de la cadena de consulta en la cadena de conexión, o como un array pasado al constructor como segundo argumento.
Aquí se establece la opción 'journal' a true y 'readPreference' al secundario preferido como predeterminado para todas las operaciones de escritura:
<?php
$m = new MongoClient("mongodb://localhost/?journal=true&readPreference=secondary");
?>
Y ahora se hace lo mismo, pero con un array de opciones:
<?php
$opciones = array(
'journal' => true,
'readPreference' => 'secondary',
);
$m = new MongoClient("mongodb://localhost/", $opciones);
?>
Ejemplo #6 Ejemplo de preferencia de lectura de MongoClient::__construct()
<?php
// Preferir el servidor más cercano en el 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.
| Versión | Descripción |
|---|---|
| 1.4.0 |
Se añadió la opción "wTimeoutMS" como sustituto de "wTimeout". |
| 1.3.4 |
Se añadieron las opciones "connectTimeoutMS" y "socketTimeoutMS". |
| 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:
|