(mongodb >=1.0.0)
MongoDB\Driver\Manager::__construct — Crea un nuevo Manager MongoDB
$uri = null, ?array $uriOptions = null, ?array $driverOptions = null)Construye un nuevo objeto MongoDB\Driver\Manager con las opciones especificadas.
Nota: Con la » Especificación de descubrimiento y supervisión del servidor, este constructor no realiza E/S. Las conexiones se inicializarán bajo demanda, durante la ejecución de la primera operación.
Nota: Cuando se especifican opciones de URI SSL o TLS a través de la cadena de conexión o el parámetro
uriOptions, la extensión activará implícitamente TLS para sus conexiones. Para evitar esto, desactive explícitamente la opcióntlso no especifique ninguna opción TLS.
Nota: En las plataformas Unix, la extensión MongoDB es sensible a los scripts que utilizan la llamada al sistema fork() sin llamar a exec(). No se deben reutilizar instancias MongoDB\Driver\Manager en un proceso hijo derivado de un fork.
uriUna URI de conexión » mongodb://:
mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[defaultAuthDb][?options]]
Para los detalles sobre las opciones de URI admitidas, ver » Opciones de cadena de conexión en el manual MongoDB. » Opciones de pool de conexiones no son admitidas, ya que la extensión no implementa pools de conexiones.
Por omisión, "mongodb://127.0.0.1:27017" si no se especifica.
El uri es una URL, por lo que todos los caracteres especiales en
sus componentes deben estar codificados en URL según la
» RFC 3986. Esto es particularmente
relevante para el nombre de usuario y la contraseña, que pueden incluir caracteres especiales tales como
@, : o %.
Al conectarse a través de un socket de dominio Unix, la ruta del socket
puede contener caracteres especiales como barras diagonales y debe estar codificada.
La función rawurlencode() puede ser utilizada para codificar
las partes constitutivas de la URI.
El componente defaultAuthDb puede ser utilizado para especificar la
base de datos asociada a las credenciales del usuario; sin embargo, la opción de URI
authSource tendrá prioridad si se especifica.
Si ni defaultAuthDb ni authSource se especifican, la base de datos
admin será utilizada por omisión. El componente defaultAuthDb
no tiene ningún efecto en ausencia de credenciales de usuario.
uriOptions
Opciones adicionales
» de cadena de conexión,
que sobrescribirán cualquier opción con el mismo nombre en el parámetro
uri.
| Opción | Tipo | Descripción |
|---|---|---|
| appname | string |
MongoDB 3.4+ tiene la capacidad de anotar las conexiones con metadatos proporcionados por el cliente conectado. Estos metadatos se incluyen en los registros del servidor al establecer una conexión y también se registran en los registros de consultas lentas cuando el perfilado de la base de datos está activado. Esta opción puede ser utilizada para especificar un nombre de aplicación, que será incluido en los metadatos. El valor no puede exceder 128 caracteres de longitud. |
| authMechanism | string |
El mecanismo de autenticación que MongoDB utilizará para autenticar la conexión. Para más detalles y una lista de los valores admitidos, ver » Opciones de autenticación en el manual MongoDB. |
| authMechanismProperties | array |
Las propiedades específicas del mecanismo de autenticación seleccionado. Para más detalles y una lista de las propiedades admitidas, ver la » Especificación de autenticación del controlador.
|
| authSource | string |
El nombre de la base de datos asociada a las credenciales del usuario. Por omisión
al componente de la base de datos de la URI de conexión, o a la base de datos
Para los mecanismos de autenticación que no admiten la noción de base de datos
(por ejemplo, GSSAPI), esto debería ser
|
| compressors | string |
Una lista priorizada y delimitada por comas de compresores que el cliente desea utilizar. Los mensajes solo se comprimen si el cliente y el servidor comparten compresores en común, y el compresor utilizado en cada dirección dependerá de la configuración individual del servidor o del controlador. Ver la » Especificación de compresión del controlador para más información. |
| connectTimeoutMS | int |
El tiempo en milisegundos para intentar una conexión antes de expirar. Por omisión, 10 000 milisegundos. |
| directConnection | bool |
Esta opción puede ser utilizada para controlar el comportamiento de descubrimiento del conjunto de réplicas
cuando solo se proporciona un host en la cadena de conexión.
Por omisión, proporcionar un solo miembro en la cadena de conexión
establecerá una conexión directa o descubrirá miembros adicionales
según si la opción de URI |
| heartbeatFrequencyMS | int |
Especifica el intervalo en milisegundos entre las verificaciones de la topología MongoDB, contado desde el final de la verificación previa hasta el inicio de la siguiente. Por omisión, 60 000 milisegundos. Para la » Especificación de descubrimiento y supervisión del servidor, este valor no puede ser inferior a 500 milisegundos. |
| journal | bool |
Corresponde a la opción |
| loadBalanced | bool |
Especifica si el controlador se conecta a un clúster MongoDB a través
de un equilibrador de carga. Si |
| localThresholdMS | int |
El tamaño en milisegundos de la ventana de latencia para la selección entre múltiples instancias MongoDB apropiadas al resolver una preferencia de lectura. Por omisión, 15 milisegundos. |
| maxStalenessSeconds | int |
Corresponde a la opción
Si se especifica, la duración máxima de validez debe ser un entero de 32 bits firmado
superior o igual a
|
| password | string | La contraseña del usuario en proceso de autenticación. Esta opción es útil si la contraseña contiene caracteres especiales, que de otro modo deberían estar codificados en URL para la URI de conexión. |
| readConcernLevel | string |
Corresponde a la opción level de la preferencia de lectura.
Especifica el nivel de aislamiento de lectura. Para más detalles, ver
MongoDB\Driver\ReadConcern.
|
| readPreference | string |
Corresponde a la opción |
| readPreferenceTags | array |
Corresponde a la opción
|
| replicaSet | string |
Especifica el nombre del conjunto de réplicas. |
| retryReads | bool |
Especifica si el controlador debe reintentar automáticamente
ciertas operaciones de lectura que fallan debido a errores de red transitorios
o elecciones de conjunto de réplicas. Esta funcionalidad requiere MongoDB 3.6+. Por omisión, Ver la » Especificación de lectura reintentable para más información. |
| retryWrites | bool |
Especifica si el controlador debe reintentar automáticamente
ciertas operaciones de escritura que fallan debido a errores de red transitorios
o elecciones de conjunto de réplicas. Esta funcionalidad requiere MongoDB 3.6+. Por omisión, Ver » Escrituras reintentables en el manual MongoDB para más información. |
| serverSelectionTimeoutMS | int |
Especifica cuánto tiempo en milisegundos bloquear para la selección del servidor antes de lanzar una excepción. Por omisión, 30 000 milisegundos. |
| serverSelectionTryOnce | bool |
Cuando |
| socketCheckIntervalMS | int |
Si un socket no ha sido utilizado recientemente, el controlador debe verificarlo a través
de un comando |
| socketTimeoutMS | int |
El tiempo en milisegundos para intentar un envío o recepción en un socket antes de expirar. Por omisión, 300 000 milisegundos (es decir, cinco minutos). |
| srvMaxHosts | int |
El número máximo de resultados SRV a seleccionar aleatoriamente durante la
primera población de la lista de semillas o, durante la consulta SRV, la adición de nuevos hosts a
la topología. Por omisión, |
| srvServiceName | string |
El nombre de servicio a utilizar para la búsqueda SRV en la lista de semillas inicial
y la consulta SRV. Por omisión, |
| tls | bool |
Inicializa la conexión con TLS/SSL si |
| tlsAllowInvalidCertificates | bool |
Especifica si el controlador debe generar un error cuando el certificado
TLS del servidor es inválido. Por omisión, Advertencia
Desactivar la validación del certificado crea una vulnerabilidad. |
| tlsAllowInvalidHostnames | bool |
Especifica si el controlador debe generar un error cuando hay un
desacuerdo entre el nombre de host del servidor y el nombre de host especificado por
el certificado TLS. Por omisión, Advertencia
Desactivar la validación del certificado crea una vulnerabilidad. Permitir nombres de host inválidos puede exponer al controlador a una » ataque del hombre del medio. |
| tlsCAFile | string |
La ruta del archivo que contiene un solo certificado o un conjunto de certificados de autoridades a considerar confiables al establecer una conexión TLS. Se utilizará el almacén de certificados del sistema por omisión. |
| tlsCertificateKeyFile | string |
La ruta del archivo de certificado del cliente o del archivo de clave privada del cliente; en el caso de que ambos sean necesarios, los archivos deben estar concatenados. |
| tlsCertificateKeyFilePassword | string |
La contraseña para descifrar la clave privada del cliente (es decir,
la opción de URI |
| tlsDisableCertificateRevocationCheck | bool |
Si |
| tlsDisableOCSPEndpointCheck | bool |
Si |
| tlsInsecure | bool |
Relaja las restricciones TLS tanto como sea posible. Especificar Advertencia
Desactivar la validación del certificado crea una vulnerabilidad. Permitir nombres de host inválidos puede exponer al controlador a una » ataque del hombre del medio. |
| username | string | El nombre de usuario del usuario en proceso de autenticación. Esta opción es útil si el nombre de usuario contiene caracteres especiales, que de otro modo deberían estar codificados en URL para la URI de conexión. |
| w | int|string |
Corresponde a la opción |
| wTimeoutMS | int|string |
Corresponde a la opción
Si se especifica, |
| zlibCompressionLevel | int |
Especifica el nivel de compresión a utilizar para el compresor zlib. Esta
opción no tiene ningún efecto si |
driverOptions
| Opción | Tipo | Descripción |
|---|---|---|
| autoEncryption | array |
Proporciona opciones para activar el cifrado automático a nivel de campo. La lista de opciones se describe en la tabla de abajo.
|
| ca_dir | string |
La ruta del directorio de certificados correctamente hashados. Se utilizará el almacén de certificados del sistema por omisión. |
| crl_file | string | La ruta del archivo de lista de revocación de certificados. |
| disableClientPersistence | bool |
Si
|
| driver | array |
Permite a un nivel superior de biblioteca añadir sus propias metadatos
al apretón de manos del servidor. Por omisión, la extensión envía su propio nombre,
versión y plataforma (es decir, versión PHP) en el apretón de manos. Las cadenas
pueden ser especificadas para las claves
|
| serverApi | MongoDB\Driver\ServerApi |
Esta opción se utiliza para declarar una versión de API de servidor para el Manager. Si se omite, no se declara ninguna versión de API. |
Las siguientes opciones son admitidas:
| Opción | Tipo | Descripción |
|---|---|---|
| keyVaultClient | MongoDB\Driver\Manager | El Manager utilizado para enrutar las peticiones de claves de datos a un cluster MongoDB diferente. Por omisión, el Manager y cluster actual es utilizado. |
| keyVaultNamespace | string | Un nombre de espacio completamente calificado (por ejemplo "databaseName.collectionName") denotando la colección que contiene todas las claves de datos utilizadas para el cifrado y descifrado. Esta opción es requerida. |
| kmsProviders | array |
Un documento que contiene la configuración de uno o varios
proveedores KMS, que se utilizan para cifrar las claves de datos.
Los proveedores soportados son
Si se especifica un documento vacío para
El formato para aws: {
accessKeyId: <string>,
secretAccessKey: <string>,
sessionToken: <optional string>
}
El formato para azure: {
tenantId: <string>,
clientId: <string>,
clientSecret: <string>,
identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
}
El formato para gcp: {
email: <string>,
privateKey: <base64 string>|<MongoDB\BSON\Binary>,
endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
}
El formato para kmip: {
endpoint: <string>
}
El formato para local: {
// 96-byte master key used to encrypt/decrypt data keys
key: <base64 string>|<MongoDB\BSON\Binary>
}
|
| tlsOptions | array |
Un documento que contiene la configuración TLS de uno o varios
proveedores KMS.
Los proveedores soportados son <provider>: {
tlsCaFile: <optional string>,
tlsCertificateKeyFile: <optional string>,
tlsCertificateKeyFilePassword: <optional string>,
tlsDisableOCSPEndpointCheck: <optional bool>
}
|
| schemaMap | array|object |
Mapea los espacios de nombres de colección a un esquema JSON local. Esto se
utiliza para configurar el cifrado automático. Ver
» Reglas de cifrado automático
en el manual MongoDB para más información. Es un error
especificar una colección tanto en
|
| bypassAutoEncryption | bool |
Si true, mongocryptd no será lanzado
automáticamente. Esto se utiliza para desactivar el cifrado automático.
Por omisión, false.
|
| bypassQueryAnalysis | bool |
Si |
| encryptedFieldsMap | array|object |
Mapea los espacios de nombres de colección a un documento
|
| extraOptions | array |
El
Ver la » Especificación de cifrado del lado del cliente para más información. |
Nota: El cifrado automático es una funcionalidad empresarial que solo se aplica a las operaciones sobre una colección. El cifrado automático no es admitido para las operaciones sobre una base de datos o una vista, y las operaciones que no son sorteadas resultarán en un error. Para sortear el cifrado automático para todas las operaciones, establezca
bypassAutoEncryption=trueenautoEncryption. Para más información sobre las operaciones admitidas, ver la » Especificación de cifrado del lado del cliente.
| Versión | Descripción |
|---|---|
| PECL mongodb 2.0.0 |
La opción de URI
La opción de URI
La opción de URI
La opción de URI
La opción de controlador
La opción de controlador
La opción de controlador
La opción de controlador
La opción de controlador
La opción de controlador |
| PECL mongodb 1.16.0 |
El proveedor AWS KMS para el cifrado del lado del cliente ahora acepta una
opción
Añadido
Si se especifica un documento vacío para el proveedor KMS |
| PECL mongodb 1.15.0 |
Si se especifica un documento vacío para el proveedor KMS |
| PECL mongodb 1.14.0 |
Añadidas las opciones de cifrado del lado del cliente |
| PECL mongodb 1.13.0 |
Añadidas las opciones de URI |
| PECL mongodb 1.12.0 |
KMIP es ahora admitido como proveedor KMS para el cifrado del lado del cliente y
puede ser configurado en el campo |
| PECL mongodb 1.11.0 |
Añadida la opción de URI |
| PECL mongodb 1.10.0 |
Añadida la opción de controlador
Azure y GCP son ahora admitidos como proveedores KMS para
el cifrado del lado del cliente y pueden ser configurados en el campo
|
| PECL mongodb 1.8.0 |
Añadidas las opciones de URI
Añadida la opción de controlador |
| PECL mongodb 1.7.0 |
Añadida la opción de controlador
Especificar cualquier opción SSL o TLS a través del parámetro
|
| PECL mongodb 1.6.0 |
Añadidas las opciones de URI
La opción de URI
Especificar una opción de URI SSL o TLS a través de la cadena de conexión o
el parámetro |
| PECL mongodb 1.5.0 |
|
| PECL mongodb 1.4.0 |
Añadidas las opciones de URI |
| PECL mongodb 1.3.0 |
El argumento |
| PECL mongodb 1.2.0 |
El argumento
Añadida la opción de URI
Añadidas las opciones de controlador
La API de flujos PHP ya no se utiliza para la comunicación por socket. La opción
|
| PECL mongodb 1.1.0 |
El argumento |
Ejemplo #1 Ejemplos básicos MongoDB\Driver\Manager::__construct()
Conexión a un nodo MongoDB autónomo:
<?php
$manager = new MongoDB\Driver\Manager("mongodb://example.com:27017");
?>Conexión a un nodo MongoDB autónomo a través de un socket de dominio Unix. La ruta del socket puede incluir caracteres especiales como barras diagonales y debe ser codificada con rawurlencode().
<?php
$manager = new MongoDB\Driver\Manager("mongodb://" . rawurlencode("/tmp/mongodb-27017.sock"));
?>Conexión a un conjunto de réplicas:
<?php
$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");
?>Conexión a un clúster fragmentado (es decir, una o más instancias mongos):
<?php
$manager = new MongoDB\Driver\Manager("mongodb://mongos1.example.com,mongos2.example.com/");
?>Conexión a MongoDB con credenciales de autenticación para un usuario y una base de datos específicos:
<?php
$manager = new MongoDB\Driver\Manager("mongodb://myusername:mypassword@example.com/?authSource=databaseName");
?>
Conexión a MongoDB con credenciales de autenticación para un usuario
y una base de datos específicos, donde el nombre de usuario o la contraseña incluye
caracteres especiales (por ejemplo @, :,
%). En el ejemplo siguiente, la cadena de contraseña
myp@ss:w%rd ha sido manualmente escapada; sin embargo,
rawurlencode() también puede ser utilizada para escapar
los componentes de la URI que pueden contener caracteres especiales.
<?php
$manager = new MongoDB\Driver\Manager("mongodb://myusername:myp%40ss%3Aw%25rd@example.com/?authSource=databaseName");
?>Conexión a MongoDB con autenticación X509:
<?php
$manager = new MongoDB\Driver\Manager(
"mongodb://example.com/?ssl=true&authMechanism=MONGODB-X509",
[],
[
"pem_file" => "/path/to/client.pem",
]
);
?>