Driver PHP do MongoDB

Introdução

Bem-vindo ao site de documentação do driver PHP oficial da MongoDB. Você pode adicionar o driver ao seu aplicativo para trabalhar com MongoDB em PHP. O driver MongoDB PHP consiste nos seguintes componentes:

• A extensão, que fornece uma API de baixo nível e serve principalmente para integrar libmongoc e libbson com PHP.

• A biblioteca, que fornece uma API de alto nível para trabalhar com bancos de dados MongoDB consistentes com outros drivers de linguagem MongoDB.

Embora seja possível usar a extensão de forma independente, o MongoDB recomenda usar a extensão e a biblioteca juntas. Para saber mais sobre os componentes do driver PHP, consulte a seção Arquitetura do driver desta página.

Navegue pelos links a seguir para saber mais sobre o driver e acessar o conteúdo do tutorial sobre como configurar um projeto executável:

• Tutorials

• Arquitetura de Extensão e Bibliotecas

• Documentação

  • Internas

  • extensão

• Registro de alterações

  • Internas

  • extensão

• código fonte

  • Internas

  • extensão

Arquitetura de driver

Esta seção descreve como os componentes do driver PHP trabalham juntos. Esses componentes se encaixam nas seguintes categorias gerais:

• API de alto nível, que inclui a biblioteca e outras integrações

• Extensão, que inclui a extensão que integra as bibliotecas de sistemas

• Sistema, que inclui o C Driver, a biblioteca BSON e a biblioteca de criptografia

O diagrama a seguir ilustra a arquitetura dos componentes do driver PHP:

A biblioteca PHP fornece uma API consistente com os outros drivers do MongoDB. A biblioteca é atualizada continuamente para atender às especificações de vários drivers. Você deve adicionar a biblioteca como uma dependência para acessar o MongoDB na maioria dos aplicativos PHP.

A extensão é distribuída por meio do PECL, e conecta o PHP às bibliotecas do sistema. A API pública da extensão fornece a seguinte funcionalidade:

• Gerenciamento de conexões

• Codificação e decodificação BSON

• Serialização de documento de objeto

• Execução de comandos

• Gerenciamento do cursor

Para saber mais sobre as bibliotecas de sistemas, consulte a documentação do Driver C.

Conecte-se a uma implantação compatível do MongoDB

Você pode usar o driver PHP para se conectar a implementações hospedadas nos seguintes ambientes:

• MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem

• MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB

• MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Instalação

Primeiro, verifique se você tem uma versão recente do PHP instalada em seu sistema. Consulte o manual oficial do PHP para obter instruções de download e instalação.

Instale a extensão PHP MongoDB antes de instalar a biblioteca PHP para MongoDB. Você pode instalar a extensão usando o PECL na linha de comando:

$ sudo pecl install mongodb

Por fim, adicione a seguinte linha ao seu arquivo php.ini:

extension=mongodb.so

O método preferido de instalar a biblioteca PHP é com o Composer executando o seguinte a partir da raiz do seu projeto:

$ composer require mongodb/mongodb

Depois de instalar a biblioteca, verifique se seu aplicativo inclui o carregador automático do Composer, como no exemplo a seguir:

<?php
require_once __DIR__ . '/vendor/autoload.php';

Instruções de instalação adicionais podem ser encontradas na documentação da biblioteca.

Ligar ao MongoDB Atlas

Você pode utilizar o seguinte trecho de conexão para testar sua conexão com seu MongoDB deployment no Atlas:

<?php
use Exception;
use MongoDB\Client;
use MongoDB\Driver\ServerApi;
// Replace the placeholder with your Atlas connection string
$uri = '<connection string>';
// Specify Stable API version 1
$apiVersion = new ServerApi(ServerApi::V1);
// Create a new client and connect to the server
$client = new MongoDB\Client($uri, [], ['serverApi' => $apiVersion]);
try {
    // Send a ping to confirm a successful connection
    $client->selectDatabase('admin')->command(['ping' => 1]);
    echo "Pinged your deployment. You successfully connected to MongoDB!\n";
} catch (Exception $e) {
    printf($e->getMessage());
}

Este trecho de conexão usa a funcionalidade Stable API, que você pode habilitar ao usar o driver PHP v1.9 e mais recentes para se conectar ao servidor MongoDB v5.0 e mais recentes. Ao usar essa funcionalidade, você pode atualizar seu driver ou servidor sem se preocupar com problemas de compatibilidade com versões anteriores com quaisquer comandos cobertos pela Stable API.

Para saber mais sobre a funcionalidade Stable API, consulte Stable API no manual do servidor.

Conecte-se ao Atlas MongoDB sem a API estável

Se estiver usando uma versão do MongoDB ou do driver não compatível com a funcionalidade Stable API, você pode usar o seguinte trecho de código para testar sua conexão com o MongoDB deployment no Atlas:

<?php
use Exception;
use MongoDB\Client;
// Replace the placeholder with your Atlas connection string
$uri = '<connection string>';
// Create a new client and connect to the server
$client = new MongoDB\Client($uri);
try {
    // Send a ping to confirm a successful connection
    $client->selectDatabase('admin')->command(['ping' => 1]);
    echo "Pinged your deployment. You successfully connected to MongoDB!\n";
} catch (Exception $e) {
    printf($e->getMessage());
}

Conecte-se a um servidor MongoDB em sua máquina local

Se você precisar executar um servidor MongoDB em seu computador local para fins de desenvolvimento, em vez de usar um cluster do Atlas, será necessário concluir o seguinte:

1. Baixe a versão Comunidade ou Enterprise do MongoDB Server.

2. Instale e configure o servidor MongoDB.

3. Inicie o servidor.

Depois de iniciar com êxito o servidor MongoDB, especifique a connection string no código de conexão do driver.

Se o servidor MongoDB estiver sendo executado localmente, você poderá usar a connection string "mongodb://localhost:<port>", em que <port> é o número da porta que você configurou no servidor para escutar as conexões de entrada.

Se você precisar especificar um nome de host ou endereço IP diferente, consulte a entrada do Manual do servidor sobre cadeias de conexão.

Para testar se você pode se conectar ao servidor, substitua a string de conexão no exemplo de código Connect to MongoDB Atlas e execute-a.

Compatibilidade

Devido a possíveis problemas que representam inteiros de 64 bits em plataformas de 32 bits, os usuários são aconselhados a usar ambientes de 64 bits. Ao utilizar uma plataforma de 32 bits, esteja ciente de que qualquer leitura de inteiro de 64bits do banco de dados será retornada como uma instância MongoDB\BSON\Int64 em vez de um tipo inteiro PHP.

Veja também

• Bibliotecas, estruturas e ferramentas PHP