/ /

Biblioteca PHP

Conectar

Docs Home

Librerías de clientes

PHP

Biblioteca PHP

Conectar

Especifica opciones de conexión

Overview

Esta página describe las opciones de conexión y autenticación de MongoDB disponibles en la librería PHP.

Configurar opciones de conexión

Puede configurar su conexión especificando opciones en el URI de conexión o pasándolas al constructor MongoDB\Client.

Uso del URI de conexión

Si pasas un URI de conexión al constructor de MongoDB\Client, puedes incluir opciones de conexión en el URI como pares <name>=<value>. En el siguiente ejemplo, el URI de conexión establece la opción tls en true y la opción tlsCertificateKeyFile en /path/to/file.pem:

// Replace the placeholders with your actual hostname, port, and path to the certificate key file
$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/file.pem';
// Create a MongoDB client
$client = new MongoDB\Client($uri);

Uso de un objeto MongoDB\Client

Puede pasar opciones de conexión al constructor MongoDB\Client en lugar de incluirlas en su URI de conexión.

El siguiente ejemplo muestra cómo usar el parámetro $uriOptions del constructor MongoDB\Client para establecer opciones de conexión:

// Replace the placeholders with your actual hostname and port
$uri = 'mongodb://<hostname>:<port>/';
// Set the connection options
// Replace the placeholder with the actual path to the certificate key file
$uriOptions = [
    'tls' => true,
    'tlsCertificateKeyFile' => '/path/to/file.pem',
];
// Create a MongoDB client with the URI and options
$client = new Client($uri, $uriOptions);

Nota

Si especificas una opción tanto en el parámetro $uriOptions como en la URI de conexión, el valor en $uriOptions tiene prioridad.

Opciones del URI de conexión

Las siguientes secciones describen las opciones que puedes configurar para tu conexión con MongoDB. Cada opción de conexión enlaza a su entrada correspondiente en el manual de MongoDB Server.

Importante

Codificación porcentaje

Si el valor de una opción de conexión contiene caracteres especiales, debe codificarlo con porcentaje antes de incluirlo en el URI de conexión. Puede utilizar el rawurlencode() método para codificar estos valores según la sintaxis URI especificada en RFC.3986

No codifiques los signos de porcentaje en las opciones de conexión al incluirlas en el parámetro $uriOptions.

Para aprender más, consulta los siguientes recursos:

RFC 3986
rawurlencode en el manual de PHP

Opciones de set de réplicas

Opción de conexión	Descripción
directConnection	Tipo de dato: `bool` Ejemplo de MongoDB\cliente: `$uriOptions = ['directConnection' => true];` Ejemplo de URI de conexión: `directConnection=true`
replicaSet	Tipo de dato: `string` Ejemplo de MongoDB\cliente: `$uriOptions = ['replicaSet' => 'replicaSetName'];` Ejemplo de URI de conexión: `replicaSet=replicaSetName`

Opciones de conexión

Opciones de TLS

Para aprender sobre las opciones de TLS disponibles en la librería de PHP, consulte la página de TLS.

Opciones de tiempo de espera

Opción de conexión	Descripción
connectTimeoutMS	Tipo de dato: `int` Ejemplo de MongoDB\cliente: `$uriOptions = ['connectTimeoutMS' => 2000];` Ejemplo de URI de conexión: `connectTimeoutMS=2000`
socketTimeoutMS	Tipo de dato: `int` Ejemplo de MongoDB\cliente: `$uriOptions = ['socketTimeoutMS' => 20000];` Ejemplo de URI de conexión: `socketTimeoutMS=20000`

Opciones de compresión

Opción de conexión	Descripción
compresores	Tipo de dato: `string` Ejemplo de MongoDB\cliente: `$uriOptions = ['compressors' => 'snappy,zstd,zlib'];` Ejemplo de URI de conexión: `compressors=snappy,zstd,zlib`
zlibCompressionLevel	Tipo de dato: `int` Ejemplo de MongoDB\cliente: `$uriOptions = ['zlibCompressionLevel' => 3];` Ejemplo de URI de conexión: `zlibCompressionLevel=3`

Opciones de nivel de confirmación de escritura

Opción de conexión	Descripción
w	Tipo de dato: `string` Ejemplo de MongoDB\cliente: `$uriOptions = ['w' => 'majority'];` Ejemplo de URI de conexión: `w=majority`
wTimeoutMS	Tipo de dato: `int` Ejemplo de MongoDB\cliente: `$uriOptions = ['wTimeoutMS' => 10000];` Ejemplo de URI de conexión: `wTimeoutMS=10000`
journal	Tipo de dato: `bool` Ejemplo de MongoDB\cliente: `$uriOptions = ['journal' => true];` Ejemplo de URI de conexión: `journal=true`

Opciones de readConcern

Opción de conexión	Descripción
readConcernLevel	Tipo de dato: `string` Ejemplo de MongoDB\cliente: `$uriOptions = ['readConcernLevel' => 'majority'];` Ejemplo de URI de conexión: `readConcernLevel=majority`

Opciones de preferencia de lectura

Opción de conexión

Descripción

readPreference

Tipo de datos: MongoDB\Driver\ReadPreference
MongoDB\Client Ejemplo: $uriOptions = ['readPreference' => 'secondaryPreferred'];
Ejemplo de URI de conexión: readPreference=secondaryPreferred

maxStalenessSeconds

Tipo de dato: int
Ejemplo de MongoDB\cliente: $uriOptions = ['maxStalenessSeconds' => 30];
Ejemplo de URI de conexión: maxStalenessSeconds=30

readPreferenceTags

Tipo de dato: array
Ejemplo de MongoDB\cliente:

$uriOptions = [
    'readPreferenceTags' => [
        ['dc' => 'ny', 'rack' => 'r1'],
        [],
    ],
];

Ejemplo de URI de conexión: readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=

Opciones de autenticación

Para aprender las opciones de autenticación disponibles en la librería PHP, consulta Mecanismos de autenticación.

Opciones de selección y descubrimiento de servidores

Opción de conexión	Descripción
localThresholdMS	Tipo de dato: `int` Ejemplo de MongoDB\cliente: `$uriOptions = ['localThresholdMS' => 20];` Ejemplo de URI de conexión: `localThresholdMS=20`
serverSelectionTimeoutMS	Tipo de dato: `int` Ejemplo de MongoDB\cliente: `$uriOptions = ['serverSelectionTimeoutMS' => 5000];` Ejemplo de URI de conexión: `serverSelectionTimeoutMS=5000`
serverSelectionTryOnce	Tipo de dato: `bool` Ejemplo de MongoDB\cliente: `$uriOptions = ['serverSelectionTryOnce' => false];` Ejemplo de URI de conexión: `serverSelectionTryOnce=false`
heartbeatFrequencyMS	Tipo de dato: `int` Ejemplo de MongoDB\cliente: `$uriOptions = ['heartbeatFrequencyMS' => 30000];` Ejemplo de URI de conexión: `heartbeatFrequencyMS=30000`
socketCheckIntervalMS	Tipo de dato: `int` Ejemplo de MongoDB\cliente: `$uriOptions = ['socketCheckIntervalMS' => 4000];` Ejemplo de URI de conexión: `socketCheckIntervalMS=4000`
`enableOverloadRetargeting`	Tipo de dato: `bool` Ejemplo de MongoDB\cliente: `$uriOptions = ['enableOverloadRetargeting' => true];` Ejemplo de URI de conexión: `enableOverloadRetargeting=true` Nota: Esta opción solo es compatible con MongoDB 9.0 o posterior.
`maxAdaptiveRetries`	Tipo de dato: `int` Ejemplo de MongoDB\cliente: `$uriOptions = ['maxAdaptiveRetries' => 3];` Ejemplo de URI de conexión: `maxAdaptiveRetries=3` Nota: Esta opción solo es compatible con MongoDB 9.0 o posterior.

Varias configuraciones

Opción de conexión	Descripción
appName	Tipo de dato: `string` Ejemplo de MongoDB\cliente: `$uriOptions = ['appName' => 'myApp'];` Ejemplo de URI de conexión: `appName=myApp`
retryReads	Tipo de dato: `bool` Ejemplo de MongoDB\cliente: `$uriOptions = ['retryReads' => false];` Ejemplo de URI de conexión: `retryReads=false`
retryWrites	Tipo de dato: `bool` Ejemplo de MongoDB\cliente: `$uriOptions = ['retryWrites' => false];` Ejemplo de URI de conexión: `retryWrites=false`
loadBalanced	Tipo de dato: `bool` Ejemplo de MongoDB\cliente: `$uriOptions = ['loadBalanced' => true];` Ejemplo de URI de conexión: `loadBalanced=true`
srvMaxHosts	Tipo de dato: `int` Ejemplo de MongoDB\cliente: `$uriOptions = ['srvMaxHosts' => 5];` Ejemplo de URI de conexión: `srvMaxHosts=5`

Nota

Reducción de carga en la gestión inteligente de la carga de trabajo (IWM)

Si los errores con las etiquetas SystemOverloadedError o RetryableError provocan fallos en su aplicación o aparecen en los registros de la misma, es posible que la función de reducción de carga esté activa en su clúster y que su controlador no esté actualizado a una versión compatible. Le recomendamos actualizar su biblioteca PHP de MongoDB a la versión 2.3 o posterior. Si estos errores persisten tras la actualización, puede solucionarlos mediante cambios en el servidor, como revisar la configuración de la reducción de carga, o mediante cambios en la aplicación, como implementar un manejo de errores personalizado o limitar las solicitudes del cliente. Según su situación, los cambios en la aplicación pueden ser preferibles o necesarios.

La función de reducción de carga es una característica de IWM que ayuda a gestionar la carga del servidor rechazando las operaciones excesivas durante una sobrecarga prolongada. Esta función está disponible en MongoDB 9.0 y versiones posteriores.

Para obtener más información sobre IWM o sobre cómo gestionar los errores de sobrecarga, consulte la página de Gestión inteligente de la carga de trabajo o la página de Errores de sobrecarga en la documentación de Atlas.

Documentación de la API

Para obtener más información sobre la clase MongoDB\Client, consulta la siguiente documentación de la API de la biblioteca PHP:

MongoDB\Client

Para obtener más información sobre la clase MongoDB\Driver\ReadPreference, consulte la siguiente documentación de la API de la extensión PHP:

MongoDB\Driver\ReadPreference

Volver

Elija un destino de conexión

Stable API