Lidando com Erros do MongoDB PHP
Avalie esse Artigo
Bem-vindo a este artigo sobre tratamento de erros do MongoDB em PHP. Amostras de código e tutoriais existem em quantidade na web , mas, para fins de clareza, eles geralmente não mostram o que fazer com possíveis erros. Nosso objetivo aqui é mostrar mecanismos comuns para lidar com possíveis problemas, como perda de conexão, incapacidade temporária de ler/gravar, falhas de inicialização e muito mais.
Este artigo foi escrito usando PHP 8.1 e MongoDB 6.1.1 (sem servidor) com a extensão PHP e a biblioteca 1.15. Como as coisas podem mudar no futuro, você pode consultar nossa documentação PHP oficial do MongoDB.
- Um cluster MongoDB Atlas com dados de amostra carregados. Temos clusters de camada gratuita do MongoDB Atlas disponíveis para todos.
- Um servidor web com PHP e o driver MongoDB PHP instalados. Idealmente, siga nosso guia "Introdução à execução do PHP com MongoDB".
- Como alternativa, você pode considerar o uso do servidor web integrado do PHP, que pode ser mais simples de configurar e pode evitar outras variações do ambiente do servidor web.
Faremos referência ao driver MongoDB PHP, que tem dois componentes distintos. Primeiro, há a extensão MongoDB PHP, que é a interface em nível de sistema para o MongoDB.
Em segundo lugar, há a Biblioteca PHP do MongoDB, uma biblioteca PHP que é a interface do aplicativo para o MongoDB. Você pode aprender sobre as pessoas por trás do nosso driver PHP neste ótimo capítulo do podcast.
Clone-o do repositório do Github para uma pasta local na seção pública do seu servidor web e site. Você pode usar o comando
Go para o diretório do projeto com o comando
e execute o comando
O Composer baixará bibliotecas externas para o diretório "vendor" (veja a captura de tela abaixo). Observe que o Composer verificará se a extensão MongoDB PHP está instalada e relatará um erro se não estiver.
Crie um arquivo .env contendo suas credenciais de usuário do banco de dados na mesma pasta que index.php. Nosso tutorial anterior descreve como fazer isso na seção "Protegendo nomes de usuário e senhas". O arquivo .env é um arquivo de texto simples formatado da seguinte forma:
MDB_USER=[nome de usuário]
MDB_PASS=[senha]
MDB_PASS=[senha]
Em seu navegador da Web, navegue até
website-url/php-error-handling-sample/, e index.php será executado.Após a execução, nosso exemplo de código gera uma página como esta, e há várias maneiras de induzir erros para ver como as várias verificações funcionam, comentando/descomentando linhas no código-fonte.
Inicialmente, os desenvolvedores se deparam com problemas no nível do sistema relacionados à configuração do PHP e se o driver PHP do MongoDB está instalado corretamente ou não. Isso é especialmente verdadeiro quando seu código é implantado em servidores que você não controla. Aqui estão dois erros comuns de tempo de execução em nível de sistema e como verificá-los:
- A extensão MongoDB está instalada e carregada?
- A biblioteca PHP do MongoDB está disponível para o seu código?
Há muitas maneiras de verificar se a extensão MongoDB PHP está instalada e carregada e aqui estão duas no artigo, enquanto as outras estão no arquivo de código.
- Você pode chamar a função
extension_loaded()do PHP commongodbcomo argumento. Retornará verdadeiro ou falso. - Você pode chamar
class_exists()para verificar a existência da classeMongoDB\Driver\Managerdefinida na extensão PHP do MongoDB. - Ligue para
phpversion('mongodb'), que deve retornar o número da versão da extensão MongoDB PHP em caso de sucesso e falso em caso de falha. - A biblioteca PHP do MongoDB também contém um arquivodetect-extention.php que mostra outra maneira de detectar se a extensão foi carregada. Este arquivo não faz parte da distribuição , mas está documentado.
Falha em qualquer um dos dois significa que a extensão PHP do MongoDB não foi carregada corretamente e você deve verificar a configuração do php.ini e os registros de erros, pois esse é um problema de configuração do sistema. Nosso artigoComeçando para executar o PHP com MongoDB fornece etapas de depuração e dicas que podem ajudá-lo.
Depois que a extensão PHP do MongoDB estiver instalada e funcionando, a próxima etapa é verificar se a biblioteca PHP do MongoDB está disponível para o seu código. Você não é obrigado a usar a biblioteca, mas é altamente recomendável que você use. Ele mantém as coisas mais abstratas, para que você se concentre em seu aplicativo em vez do funcionamento interno do MongoDB.
Procure a classe
MongoDB\Client. Se estiver lá, a biblioteca foi adicionada ao seu projeto e está disponível no tempo de execução.Agora você pode instanciar um cliente com sua connection string. (Veja como localizar a connection string do Atlas.)
A instanciação falhará se algo estiver errado com a análise da connection string ou se o driver não conseguir resolver o registro SRV (DNS) da conexão. As possíveis causas para falhas na resolução de SRV incluem o endereço IP sendo rejeitado pelo cluster MongoDB ou problemas de conexão de rede ao verificar o SRV.
Até este ponto, a biblioteca acabou de construir um gerenciador de driver interno e nenhuma E/S no cluster foi realizada. Esse comportamento é descrito nesta página de documentação da biblioteca PHP — consulte a seção "Comportamento".
É importante saber que, embora o cliente tenha sido instanciado com sucesso, isso não significa que seu par de usuário/senha seja válido e não concede acesso automático a nada. Seu código ainda não tentou acessar nenhuma informação, então sua autenticação não foi verificada.
Quando você cria pela primeira vez um cluster do MongoDB Atlas, há um botão "Conectar" na interface do usuário para recuperar o URL da instância. Se não existir nenhum banco de dados de usuário, você será solicitado a adicionar um e adicionar um endereço IP à lista de acesso.
Na barra lateral da GUI do MongoDB Atlas, há uma seção "Segurança" com links para as páginas de configuração "Acesso ao banco de dados" e "Acesso à rede". "Database Access" é onde você cria usuários do bancode dados e seus privilégios. "Acesso à rede" permite adicionar endereços IP à lista de acesso IP.
Em seguida, você pode fazer uma primeira operação que requer uma conexão de E/S e uma autenticação, como listar os bancos de dados com
listDatabaseNames(), conforme mostrado no bloco de código abaixo. Se for bem-sucedido, seu par de usuário/senha será válido. Se falhar, pode ser que o par seja inválido ou o usuário não tenha os privilégios adequados.Há outras razões pelas quais qualquer comando MongoDB pode falhar (perda de conectividade, etc.), e a mensagem de exceção revelará isso. Essas primeiras etapas de inicialização são pontos comuns de atrito, pois os URLs do cluster variam de projeto para projeto, os IPs mudam e as senhas são redefinidas.
Se você ainda não executou a operação CRUD com o MongoDB antes, temos um ótimo tutorial intitulado "Criando, lendo, atualizando e excluindo documentos do MongoDB com PHP". Aqui, vamos dar uma olhada nos mecanismos de tratamento de erros.
Iremos acessar um dos MongoDB database de amostra denominado "sample_analytics," e ler/gravar na coleção "clientes". Se você não estiver familiarizado com a terminologia do MongoDB, aqui está uma rápida visão geral do MongoDBdatabase e das coleções do MongoDB.
Às vezes, garantir que o cluster conectado contenha os bancos de dados e as collections esperados pode ser uma boa ideia. Em nossa amostra de código, podemos verificar o seguinte:
As operações CRUD do MongoDB têm uma variedade de motivos legíveis para encontrar uma exceção. A forma geral de lidar com esses erros é colocar sua operação em um bloco try/catch para evitar um erro fatal.
Se nenhuma exceção for encontrada, a maioria das operações retornará um documento contendo informações sobre como foi a operação.
Por exemplo, as operações de gravação retornam um documento que contém um booliano "isAcknowledged" de preocupação de gravação e um objetoWriteResult . Ele tem dadosde feedback importantes, como o número de documentos correspondentes e modificados ( entre outras coisas). Seu aplicativo pode verificar se a operação foi executada conforme o esperado.
Se uma exceção ocorrer, você poderá adicionar mais verificações para ver exatamente que tipo de exceção. Para referência, examine a árvore de classes de exceções do MongoDB e lembre-se de que você pode obter mais informações da exceção do que apenas a mensagem. A classe ServerException do driver também pode fornecer o código de erro de exceção , a linha de código-fonte e o rastreamento e muito mais!
Por exemplo, uma exceção comum ocorre quando o aplicativo tenta inserir um novo documento com um ID exclusivo existente. Isso pode acontecer por vários motivos, inclusive em situações de alta simultaneidade em que vários threads ou clientes podem tentar criar registros idênticos.
O MongoDB mantém uma série de testes para sua biblioteca PHP (consulte DocumentationExamplesTest.php no Github). Ele contém ótimos exemplos de código de várias queries, com tratamento de erros. É altamente recomendável consultá-lo e usá-lo como referência, pois ele se manterá atualizado com os drivers e as APIs mais recentes.
Este artigo teve como objetivo apresentar o tratamento de erros do MongoDB em PHP, destacando as armadilhas comuns e as perguntas frequentes que respondemos. Compreender os vários mecanismos de tratamento de erros do MongoDB tornará seu aplicativo sólido, simplificará seu fluxo de trabalho de desenvolvimento e, por fim, tornará você e sua equipe mais produtivos.
Para saber mais sobre como usar o MongoDB em PHP, aprenda com nosso tutorial da Biblioteca PHP, e nós o convidamos a se conectar por meio da seção PHP de nossos fóruns da comunidade de desenvolvedores.
- Documentação do driver MongoDB PHP fornece documentação completa que descreve como usar PHP com seu cluster do MongoDB.
- A documentação do documento de query do MongoDB detalha todo o poder disponível para consultar collections do MongoDB.
Avalie esse Artigo