(PECL mongo >=1.3.0)
MongoClient::__construct — Crea un nuevo objeto de conexión a base de datos
Esta extenisón que define este método está obsoleta. En su lugar debe usarse la extensión MongoDB. Las alternativas a este método son:
$server = "mongodb://localhost:27017"
[, array $options = array("connect" => TRUE)
[, array $driver_options
]]] )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
El string de conexión siempre comienza con mongodb://, para indicar que es un string 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 un string 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:
"authMechanism"
Los mecanismos de autenticación son:
| authMechanism | Descripción | Disponibilidad |
|---|---|---|
| MONGODB-CR | Autenticar usando el mecanismo de Respuesta de Reto. Este es el valor predeterminado. | Todas las versiones de MongoDB |
| X509 | Autenticar usando certificados X509 | MongoDB 2.6. Solamente disponible si OpenSSL está habilitado |
| PLAIN | Autenticar usando nombre_usuario+contraseña plano no encriptado. Debe usarse sobre conexiones SSL. Generalmente usado por MongoDB para identificarse mediante un servidor LDAP de terceros | MongoDB Enterprise 2.4. El controlador debe compilarse con CyrusSASL2 |
| GSSAPI | Autenticar mediante sistemas kerberos | MongoDB Enterprise 2.4. El controlador debe compilarse con CyrusSASL2 |
"authSource"
Debería estar establecido al nombre de la base de datos cuando lo defina.
"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 del string de conexión.
"connectTimeoutMS"
Cuánto puede tomar una conexión para ser abierta antes de expirar en milisegundos. El valor predeterminado es 60000 (60 segundos).
Si se especifica -1, no se aplicará un tiempo límite a la conexión y PHP usará default_socket_timeout.
"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 "fsync" está establecido, todas las operaciones de escritura bloquearán hasta que la base de datos haya volcado los cambios al disco. Esto hace que las operaciones de escritura sean más lentas, pero garantiza su éxito y que puedan ser recuperadas en caso de un fallo total del sistema.
Si el servidor de MongoDB tiene el registro en el diario habilitado, esta opción es idéntica a "journal". Si el registro no está habilitado, esta opción se asegura de que las operaciones de escritura se sincronicen con los ficheros de la base de dato del disco.
Nota: Si el registro en el diario está habilitado, se recomienda utilizar la opción "journal" en lugar de "fsync". No use "fsync" y "journal" simultáneamente, ya que resultará en un error.
"journal"
Cuando "journal" está establecido, todas las operaciones de escritura bloquearán hasta que la base de datos haya volcado los cambios del diario al disco. Esto hace que las operaciones de escritura sean más lentas, pero garantiza su éxito y que puedan ser recuperadas en caso de un fallo total del sistema.
Nota: Si está operación se usa y el registro en el diario está deshabilitado, MongoDB 2.6+ emitirá un error y la escritura fallará; las versiones más antiguas del servidor simplemente ignorarán esta opción.
"gssapiServiceName"
Establece el » Jefe de servicios de Kerberos. Aplicable solamente si authMechanism=GSSAPI. El valor predeterminado es "mongodb".
"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 se determinará automáticamente. 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.
"secondaryAcceptableLatencyMS"
Cuando se lee de un secundario (usando ReadPreferences), no leer de secundarios que se sabe que están a más de secondaryAcceptableLatencyMS de nosotros. El valor predeterminado es 15
"socketTimeoutMS"
Cuánto puede tomar una operación de socket (lectura o escritura) antes de expirar, en milisegundos. El valor predeterminado es 30000 (30 segundos).
Si se especifica -1, las operaciones de socket podrían quedar en espera indefinidamente. Esta opción también podría establecerse de acuerdo a cada operación usando MongoCursor::timeout() para consultas o la opción "socketTimeoutMS" para métodos de escritura.
Nota: Este es un tiempo límite del lado del cliente. Si un una operación de escritura expira, no hay forma de saber si el servidor manejó realmente la escritura o no, ya que se lanzará una MongoCursorTimeoutException en lugar de devolver un resultado de 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 especifica el tiempo límite, en milisegundos, para el reconocimiento de un asunto de escritura. Solamente es aplicable para operaciones de escritura donde "w" sea mayor que 1, ya que el tiempo de espera está relacionado con la replecación. Si el asunto de escritura no se satisface dentro del tiempo límite, se lanzará una MongoCursorException. Se puede especificar un valor de 0 para bloquear indefinidamente. El valor predeterminado es 10000 (diez segundos).
Las siguientes opciones están obsoletas y no deberían usarse más:
"slaveOkay"
Obsoleta. Use las opciones de preferencias de lectura.
"timeout"
Alias obsoleto de "connectTimeoutMS".
"wTimeout"
Alias obsoleto de "wTimeoutMS".
driver_options
Un array de opciones para el controlador de MongoDB. Las opciones incluyen los ajustes de conexión opciones de contexto para SSL o retrollamadas de identificación.
"context"
El contexto de flujo a adjuntar a todas las conexiones nuevas. Esto permite, por ejemplo, configurar certificados SSL. Están descritos en las opciones de contexto de SSL. Véase el tutorial Conectar sobre SSL.
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 el string 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 del string de consulta en el string 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.5.0 |
Se añadieron "authMechanism", "gssapiServiceName", y "secondaryAcceptableLatencyMS". |
| 1.4.0 |
Se añadió la opción "ssl" y el soporte para conexiones sobre SSL. Se añadió la opción "wTimeoutMS", que remplaza a "wTimeout".
Emite un error de nivel |
| 1.5.0 |
Se añadió "authSource". |
| 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:
|