Perguntas frequentes

Erros comuns de instalação de extensões

/private/tmp/pear/install/mongodb/php_phongo.c:24:10: fatal error: 'php.h' file not found
#include <php.h>
         ^~~~~~~

php vendor/mongodb/mongodb/tools/detect-extension.php

<pre><?php require(...); ?></pre>

PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb'

Tratamento e persistência de conexões

As conexões com o MongoDB deployment são tratadas pela libmongoc biblioteca e pela extensão PHP. Quando você constrói uma MongoDB\Client instância do, a biblioteca PHP cria uma instância MongoDB\Driver\Manager usando 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. Você pode saber mais sobre esse processo na 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. Isso significa que as conexões com uma implantação do MongoDB 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 um sistema do MongoDB , pode ser problemático em algumas situações, descritas na lista a seguir:

• 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/',
    uriOptions: [],
    driverOptions: ['disableClientPersistence' => true],
);

Use a opção de driver disableClientPersistence após uma consideração cuidadosa, pois desativar a persistência do cliente requer mais tempo para estabelecer conexões com a implantação do MongoDB e descobrir sua topologia.

Falhas de seleção do servidor

Os itens a seguir são exemplos de falhas de seleção de servidor :

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

Esses erros normalmente se manifestem como uma exceção do MongoDB\Driver\Exception\ConnectionTimeoutException exceção da extensão. As mensagens de exceção reais são originadas da libmongoc, que é a biblioteca do sistema subjacente usada pela extensão. Como essas mensagens podem assumir várias formas, é útil detalhar a estrutura da mensagem para que você possa diagnosticar melhor os erros em seu aplicação.

Normalmente, as mensagens começam com "Nenhum servidor adequado encontrado". A próxima parte da mensagem indica como a seleção do servidor falhou. Por padrão, a extensão evita um loop de seleção de servidor e, em vez disso, faz uma única tentativa (de acordo com a opção de string de conexão serverSelectionTryOnce ). Se a extensão estiver configurada para utilizar um loop, uma mensagem como "serverSelectionTimeoutMS expired" nos informará que esgotamos 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 analisador de topologia, que é o serviço responsável por conectar e monitorar cada host. Qualquer host que tenha experimentado um erro pela última vez durante o monitoramento será incluído nesta lista. Essas mensagens normalmente se originam de funções de soquete ou TLS de baixo nível.

O seguinte não pretende ser exaustivo, mas espera-se que direcione você na direção correta para analisar os fatores que contribuem para uma falha de seleção de servidor:

• "conexão recusada" provavelmente indica que o host remoto não está escutando na porta esperada.

• "tempo limite de conexão" pode indicar um problema de roteamento ou firewall, ou talvez um tempo limite devido à latência.

• "tempo limite do soquete" sugere que uma conexão foi estabelecida em algum ponto, mas foi descartada ou atingiu o tempo limite devido à latência.

• "Falha no handshake TLS" sugere algo relacionado à verificação TLS ou OCSP e, às vezes, é indicativo de certificados TLS configurados incorretamente.

No caso de uma falha de conexão, você pode utilizar a ferramenta connect para tentar receber mais informações. Essa ferramenta tenta se conectar a cada host em uma string de conexão usando funções de soquete para ver se ela é capaz de estabelecer uma conexão, enviar e receber dados. A ferramenta usa a string de conexão para um sistema do MongoDB como seu único argumento. Supondo que você tenha instalado a biblioteca por meio do Composer, chame o script a partir do diretório do fornecedor:

php vendor/mongodb/mongodb/tools/connect.php mongodb://127.0.0.1:27017

Caso o servidor não aceite conexões, a saída será assim:

Looking up MongoDB at mongodb://127.0.0.1:27017
Found 1 host(s) in the URI. Will attempt to connect to each.
Could not connect to 127.0.0.1:27017: Connection refused