Escolha um destino de conexão

Visão geral

Neste guia, você pode aprender como usar uma string de conexão e objeto MongoDB\Client para conectar a diferentes tipos de sistemas MongoDB.

Atlas

Para se conectar a uma MongoDB deployment no Atlas, inclua os seguintes elementos em sua connection string:

• URI do seu Atlas cluster

• Nome de usuário do banco de dados

• Senha do usuário do banco de dados

Em seguida, passe sua connection string para o construtor MongoDB\Client .

Ao se conectar ao Atlas, recomendamos usar a opção de cliente Stable API para evitar alterações significativas quando o Atlas atualizar para uma nova versão do MongoDB Server. Para saber mais sobre o recurso de Stable API , consulte apágina deStable API .

O código abaixo mostra como usar a biblioteca PHP para se conectar a um Atlas cluster. O código também usa a opção serverApi para especificar uma versão da Stable 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';

Implantações locais

Para se conectar a uma implantação local do MongoDB, use localhost como nome do host. Por padrão, o processo mongod é executado na porta 27017, embora você possa personalizar isso para seu sistema.

O seguinte código mostra como usar a biblioteca PHP para se conectar a uma implementação local do MongoDB :

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

Conjuntos de réplicas

Para se conectar a um conjunto de réplicas, especifique o nome de host (ou o endereço IP) e o número de porta dos membros do conjunto de réplicas em sua string de conexão.

Se você não conseguir fornecer uma lista completa de hosts no conjunto de réplicas, poderá especificar um ou mais hosts no conjunto de réplicas e instruir a biblioteca PHP a executar a descoberta automática para encontrar os outros. Para instruir o driver a executar a descoberta automática, escolha uma das seguintes ações:

• Especifique o nome do conjunto de réplica como o valor do parâmetro replicaSet.

• Especifique false como o valor do parâmetro directConnection.

• Especifique mais de um host no conjunto de réplica.

No exemplo a seguir, o driver usa um URI de conexão de exemplo para se conectar ao conjunto de réplicas do MongoDB sampleRS, que está sendo executado na porta 27017 de três hosts diferentes, incluindo 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);

Descoberta de serviço DNS

Para usar a descoberta de serviços DNS para procurar o registro DNS SRV do serviço ao qual você está se conectando, especifique o formato de conexão SRV em sua string de conexão. Se você especificar este formato, a biblioteca PHP reanalisará automaticamente em busca de novos hosts. Seu sistema pode adicionar hosts à topologia sem exigir alterações na configuração do cliente .

O código a seguir mostra uma string de conexão que usa o formato de conexão SRV:

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

Para saber mais sobre o formato de conexão SRV, consulte a entrada Formato de conexão SRV no manual do MongoDB Server.

Erros de seleção do servidor

O código a seguir mostra possíveis mensagens de erro de seleção de servidor que seu aplicação pode gerar:

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']

The PHP extension usually represents these errors as MongoDB\Driver\Exception\ConnectionTimeoutException exceptions. However, the exception messages originate from libmongoc, which is the underlying system library used by the extension. Since these messages can take many forms, we recommend breaking down the structure of the message so you can better diagnose errors in your application.

As mensagens normalmente começam com "Nenhum servidor adequado encontrado". A próxima parte da mensagem indica como a seleção do servidor falhou. A extensão evita um loop de seleção de servidor e faz uma única tentativa por padrão, de acordo com a opção de string de conexão serverSelectionTryOnce. Se a extensão estiver configurada para usar um loop, uma mensagem que inclui a frase "serverSelectionTimeoutMS expired" indica que você esgotou seu limite de tempo.

O último componente da mensagem nos informa por que a seleção do servidor falhou e inclui um ou mais erros diretamente do scanner de topologia, que é o serviço responsável por conectar e monitorar cada host. Qualquer host que tenha experimentado um erro anteriormente durante o monitoramento será incluído nesta lista. Essas mensagens normalmente se originam de soquete de baixo nível ou funções TLS.

A lista a seguir descreve os possíveis significados de frases comuns no último componente de mensagem de erro:

• "Conexão recusada": o host remoto pode não estar escutando na porta esperada.

• "Timeout da conexão": pode haver um problema de roteamento, um erro de firewall ou um tempo limite devido à latência.

• "Timeout do soquete": você provavelmente estabeleceu uma conexão inicial que foi descartada ou atingiu o tempo limite devido à latência.

• "Falha no handshake TLS": a verificação do TLS ou OCSP não foi bem-sucedida e você pode estar usando certificados TLS configurados incorretamente.

No caso de uma falha de conexão, você pode utilizar a ferramenta connect para obter mais informações de solução de problemas. Esta ferramenta tenta se conectar a cada host em uma string de conexão usando funções de soquete e, em seguida, tenta interagir com dados. Se você usou o Composer para instalar a biblioteca, você pode usar o seguinte comando para iniciar a ferramenta connect:

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

Se o servidor ao qual você está se conectando não aceitar conexões, a saída será semelhante ao seguinte 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

Documentação da API

Para saber mais sobre como usar a classe MongoDB\Client , consulte a seguinte documentação da API:

• MongoDB\Client