Elija un destino de conexión

Overview

En esta guía, puede aprender a utilizar una cadena de conexión y MongoDB\Client objeto para conectarse a diferentes tipos de implementaciones de MongoDB.

Atlas

Para conectarse a una implementación de MongoDB en Atlas, incluya los siguientes elementos en su cadena de conexión:

• URI de su clúster Atlas

• Nombre de usuario de la base de datos

• Contraseña del usuario de la base de datos

Luego, pase la cadena de conexión al constructor MongoDB\Client.

Al conectarse a Atlas, recomendamos usar la opción de cliente API estable para evitar cambios importantes cuando Atlas se actualice a una nueva versión de MongoDB Server. Para obtener más información sobre la función API estable, consulte Página API estable.

El siguiente código muestra cómo usar la librería PHP para conectarse a un clúster Atlas. El código también utiliza la opción serverApi para especificar una versión estable de la API.

<?php
// Replace the placeholder with your Atlas connection string
$uri = '<connection string>';
// Create a MongoDB client with server API options
$client = new MongoDB\Client($uri, [], [
    'serverApi' => new MongoDB\Driver\ServerApi('1'),
]);
// Ping the server to verify that the connection works
$admin = $client->admin;
$command = new MongoDB\Driver\Command(['ping' => 1]);
$result = $admin->command($command)->toArray();
echo json_encode($result), PHP_EOL;
echo 'Pinged your deployment. You successfully connected to MongoDB!\n';

Implementaciones locales

Para conectarse a una implementación local de MongoDB, use localhost como nombre de host. De forma predeterminada, el proceso mongod se ejecuta en el puerto 27017, aunque puede personalizarlo para su implementación.

El siguiente código muestra cómo utilizar la biblioteca PHP para conectarse a una implementación local de MongoDB:

<?php
$uri = 'mongodb://localhost:27017';
$uriOptions = ['serverSelectionTimeoutMS' => 10000];
$client = new MongoDB\Client($uri, $uriOptions);

Sets de réplicas

Para conectarse a un conjunto de réplicas, especifique los nombres de host (o direcciones IP) y los números de puerto de los miembros del conjunto de réplicas en su cadena de conexión.

Si no puede proporcionar una lista completa de hosts en el conjunto de réplicas, puede especificar uno o más de ellos e indicar a la biblioteca PHP que realice la detección automática para encontrar los demás. Para indicar al controlador que realice la detección automática, elija una de las siguientes acciones:

• Especifique el nombre del conjunto de réplicas como el valor del parámetro replicaSet.

• Especifique false como el valor del parámetro directConnection.

• Especifica más de un host en el conjunto de réplicas.

En el siguiente ejemplo, el controlador utiliza un URI de conexión de muestra para conectarse al conjunto de réplicas de MongoDB sampleRS, que se ejecuta en el puerto 27017 de tres hosts diferentes, incluido host1:

<?php
$uri = 'mongodb://host1:27017/?replicaSet=sampleRS';
// Create a MongoDB client
$client = new MongoDB\Client($uri);

<?php
// Replace the placeholders with your actual hostname and port
$uri = 'mongodb://<hostname>:<port>/?directConnection=true';
// Create a MongoDB client
$client = new MongoDB\Client($uri);

Detección de servicios DNS

Para usar la detección de servicios DNS y buscar el registro SRV DNS del servicio al que se conecta, especifique el formato de conexión SRV en la cadena de conexión. Si especifica este formato, la biblioteca PHP vuelve a escanear automáticamente en busca de nuevos hosts. Su implementación puede agregar hosts a su topología sin necesidad de modificar la configuración del cliente.

El siguiente código muestra una cadena de conexión que utiliza el formato de conexión SRV:

$uri = 'mongodb+srv://<hostname>/';

Para obtener más información sobre el formato de conexión SRV, consulte la Entrada deformato de conexión SRV en el manual del servidor MongoDB.

Errores de selección del servidor

El siguiente código muestra posibles mensajes de error de selección de servidor que su aplicación podría generar:

No suitable servers found (`serverSelectionTryOnce` set):
  [connection refused calling hello on 'a.example.com:27017']
  [connection refused calling hello on 'b.example.com:27017']
No suitable servers found: `serverSelectionTimeoutMS` expired:
  [socket timeout calling hello on 'example.com:27017']
No suitable servers found: `serverSelectionTimeoutMS` expired:
  [connection timeout calling hello on 'a.example.com:27017']
  [connection timeout calling hello on 'b.example.com:27017']
  [TLS handshake failed: -9806 calling hello on 'c.example.com:27017']
No suitable servers found: `serverselectiontimeoutms` timed out:
 [TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'a.example.com:27017']
 [TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'b.example.com:27017']

La extensión PHP generalmente representa estos errores como MongoDB\Driver\Exception\ConnectionTimeoutExceptionExcepciones. Sin embargo, los mensajes de excepción se originan libmongoc en, la biblioteca del sistema subyacente que utiliza la extensión. Dado que estos mensajes pueden adoptar diversas formas, recomendamos desglosar su estructura para diagnosticar mejor los errores en la aplicación.

Los mensajes suelen comenzar con "No se encontraron servidores adecuados". La siguiente parte del mensaje indica cómo falló la selección del servidor. La extensión evita un bucle de selección de servidor y realiza un único intento por defecto, según la serverSelectionTryOnce opción de cadena de conexión. Si la extensión está configurada para usar un bucle, un mensaje con la frase "serverSelectionTimeoutMS expired" indica que se agotó el tiempo límite.

El último componente del mensaje indica el motivo del fallo en la selección del servidor e incluye uno o más errores directamente del escáner de topología, el servicio responsable de conectar y supervisar cada host. Cualquier host que haya experimentado un error durante la supervisión se incluirá en esta lista. Estos mensajes suelen provenir de funciones de sockets de bajo nivel o TLS.

La siguiente lista describe los posibles significados de frases comunes en el último componente del mensaje de error:

• "Conexión rechazada": es posible que el host remoto no esté escuchando en el puerto esperado.

• "Tiempo de espera de conexión": puede haber un problema de enrutamiento, un error de firewall o un tiempo de espera debido a la latencia.

• "Tiempo de espera de socket": es probable que hayas establecido una conexión inicial que se interrumpió o se agotó debido a la latencia.

• "Error en el protocolo de enlace TLS": la verificación TLS u OCSP no se realizó correctamente y es posible que esté usando certificados TLS mal configurados.

En caso de fallo de conexión, puede usar la herramienta connect para obtener más información sobre la solución de problemas. Esta herramienta intenta conectarse a cada host de una cadena de conexión mediante funciones de socket y, a continuación, intenta interactuar con los datos. Si utilizó Composer para instalar la biblioteca, puede usar el siguiente comando para iniciar la herramienta connect:

php vendor/mongodb/mongodb/tools/connect.php <connection URI>

Si el servidor al que se está conectando no acepta conexiones, la salida se parecerá al siguiente código:

Looking up MongoDB at <connection URI>
Found 1 host(s) in the URI. Will attempt to connect to each.
Could not connect to <host>:<port>: Connection refused

Documentación de la API

Para obtener más información sobre el uso de la clase MongoDB\Client, consulte la siguiente documentación de API:

• MongoDB\Client