Elija un destino de conexión

Overview

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

Atlas

Para conectarte a una implementación de MongoDB en Atlas, incluye los siguientes elementos en tu cadena de conexión:

• URI de tu clúster de Atlas

• Nombre de usuario de la base de datos

• Contraseña del usuario de base de datos

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

Cuando se conecte a Atlas, se recomienda utilizar la opción de cliente de Stable API para evitar cambios disruptivos al actualizar a una nueva versión de MongoDB Server en Atlas. Para obtener más información sobre la funcionalidad Stable API, consulta 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 el nombre de host. Por defecto, el proceso mongod se ejecuta en el puerto 27017, aunque puedes personalizarlo para tu implementación.

El siguiente código muestra cómo utilizar la librería 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 set 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 está funcionando en el puerto 27017 de tres hosts diferentes, incluyendo 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 utilizar el descubrimiento de servicios DNS para buscar el registro DNS SRV del servicio al que te estás conectando, especifica el formato de conexión SRV en la cadena de conexión. Si especificas este formato, la librería PHP vuelve a analizar automáticamente la presencia de nuevos hosts. La implementación puede añadir hosts a su topología sin requerir cambios en 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, consulta el Formato de conexión SRV entrada en el manual de MongoDB Server.

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 normalmente representa estos errores como MongoDB\Driver\Exception\ConnectionTimeoutException excepciones. Sin embargo, los mensajes de excepción provienen de libmongoc, que es la librería de sistema subyacente utilizada por la extensión. Dado que estos mensajes pueden adoptar múltiples formas, se recomienda desglosar la estructura del mensaje para poder diagnosticar mejor los errores de 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 nos indica por qué falló la selección del servidor e incluye uno o más errores directamente del escáner de topología, que es el servicio responsable de conectar y monitorear cada host. Cualquier host que haya experimentado previamente un error durante la supervisión será incluido en esta lista. Estos mensajes suelen originarse a partir de funciones de socket o TLS de bajo nivel.

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": Podría 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.

• "Fallo en el handshake TLS": la verificación TLS u OCSP no tuvo éxito, y es posible que estés utilizando certificados TLS mal configurados.

En caso de fallo de la conexión, puedes utilizar la herramienta connect para obtener más información sobre la solución de problemas. Esta herramienta intenta conectarse a cada host en una cadena de conexión utilizando funciones de socket y luego intenta interactuar con los datos. Si utilizaste Composer para instalar la librería, puedes 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