Criar um cliente MongoDB

Visão geral

Para se conectar a uma MongoDB deployment, você deve criar os seguintes itens:

• O URI de conexão, também conhecido como string de conexão, informa à biblioteca PHP a qual sistema do MongoDB se conectar.

• objeto MongoDB \Client , que cria a conexão com a implantação do MongoDB e permite que você execute operações nele.

Você também pode definir opções em um ou em ambos os componentes para personalizar a maneira como a biblioteca PHP se comporta enquanto conectada ao MongoDB.

Este guia descreve os componentes de uma string de conexão e mostra como usar um objeto MongoDB\Client para se conectar a um MongoDB deployment.

URI de conexão

Uma connection string padrão inclui os seguintes componentes:

Para saber mais sobre connection strings, consulte connection strings no manual do servidor.

Criar um MongoDB\Client

Para criar uma conexão com o MongoDB, construa um objeto MongoDB\Client. Passe os seguintes parâmetros para o construtor MongoDB\Client:

• $uri: define o URI de conexão.

• $uriOptions: (Opcional) Define opções de URI para configurar como o cliente se conecta ao MongoDB, incluindo credenciais de autenticação e configurações de seleção do servidor . Se você definir as mesmas opções neste parâmetro e em sua string de conexão, os valores $uriOptions terão precedência. Para visualizar uma lista completa de opções suportadas, consulte o guia Especificar opções de conexão.

• $driverOptions: (Opcional) Define opções para configurar o comportamento da extensão PHP subjacente, incluindo configurações de criptografia de dados e opções de validação de certificado para conexões TLS. Para visualizar uma lista completa de opções suportadas, consulte MongoDB\Client::__construct() na documentação da API.

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

Persistência do cliente

A libmongoc biblioteca do e a extensão PHP lidam com conexões para uma implantação MongoDB . Quando você constrói uma instância do, a MongoDB\Client biblioteca PHP cria uma instância do MongoDB\Driver\Manager utilizando a mesma string de conexão e opções. A extensão também usa esses argumentos do construtor para derivar uma chave de hash para libmongoc clientes persistentes. Se você persistiu anteriormente um libmongoc cliente usando uma chave, ela será reutilizada. Caso contrário, um novo libmongoc cliente é criado e mantido durante a vida útil do processo de trabalho PHP. Para saber mais sobre esse processo, consulte a documentação da extensão PHP.

Cada cliente do libmongoc mantém suas próprias conexões com a implantação do MongoDB e uma visualização de sua topologia. Quando você reutiliza um cliente libmongoc persistente, a biblioteca PHP pode evitar a sobrecarga de estabelecer novas conexões e redescobrir a topologia. Essa abordagem geralmente melhora o desempenho e é o comportamento padrão do driver.

Clientes persistentes libmongoc não são liberados até que o processo de trabalho PHP termine. Como resultado, as conexões com uma MongoDB deployment podem permanecer abertas depois que um objeto MongoDB\Driver\Manager sair do escopo. Embora isso normalmente não seja um problema para aplicativos que se conectam a uma implantação do MongoDB , isso pode causar erros nas seguintes situações:

• O PHP-FPM é configurado com pm.max_requests=0 para que os trabalhadores nunca reapareçam e um aplicação PHP é implantado muitas vezes com pequenas alterações em sua string de conexão ou opções do MongoDB . Isso pode levar a um acúmulo de libmongoc objetos de cliente em cada processo de trabalho.

• Ocasionalmente, um aplicação se conecta a um sistema separado do MongoDB em um componente de backend onde a latência de solicitação não é o aspecto mais importante.

No primeiro caso, reiniciar o PHP-FPM como parte do sistema do aplicação permite que o aplicação libere todos os clientes libmongoc não utilizados e ainda use um cliente persistente para a string de conexão mais recente.

O segundo caso exige uma solução diferente. A especificação de true para a opção de driver disableClientPersistence instrui a biblioteca PHP a criar um novo cliente libmongoc e garantir que ele seja liberado quando o MongoDB\Driver\Manager correspondente sair do escopo.

O código abaixo demonstra como definir a opção disableClientPersistence como true ao criar um cliente:

<?php
$client = new MongoDB\Client(
    uri: getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/',
    driverOptions: ['disableClientPersistence' => true],
);

Documentação da API

Para saber mais sobre como criar um objeto MongoDB\Client na biblioteca PHP, consulte a seguinte documentação da API:

• MongoDB\Client