Conecte seu aplicativo Laravel ao MongoDB

Visão geral

Neste guia, você aprenderá como conectar seu aplicativo Laravel a uma instância do MongoDB ou a um sistema de conjunto de réplicas usando o Laravel MongoDB.

Este guia inclui as seguintes seções:

URI de conexão, que explica os URIs de conexão e suas partes constituintes
Configuração da conexão do banco de dados Laravel, que explica como configurar sua conexão do MongoDB database para seu aplicativo Laravel.
Exemplo de conexão, que fornece exemplos que mostram como se conectar ao MongoDB usando uma connection string do Atlas.
Outras Maneiras de Conectar ao MongoDB descreve maneiras de se conectar a implementações do MongoDB que não estão hospedadas no Atlas.

URI de conexão

Um URI de conexão, também conhecido como string de conexão, especifica como a integração do Laravel se conecta ao MongoDB e como se comportar enquanto estiver conectado.

Partes de um URI de conexão

Uma connection string inclui os seguintes componentes:

Componente	Descrição
`mongodb://` ou `mongodb+srv://`	Obrigatório. Um prefixo que identifica o URI como uma string no formato de conexão padrão (`mongodb://`) ou no formato de conexão SRV (`mongodb+srv://`). Para obter mais informações, consulte Formatos de cadeia de conexão.
`username:password`	Opcional. Especifica seu nome de usuário e senha do banco de dados para autenticação usando o formato `<username>:<password>`. Omita esta seção se sua implantação não exigir autenticação.
`host[:port]`	Obrigatório. O host e o número da porta opcional em que o MongoDB está sendo executado. Se você não incluir o número da porta, o driver usará a porta padrão, `27017`. Observe que a especificação do número da porta só é suportada ao usar o formato de conexão padrão. Se você estiver usando o formato de conexão SRV, omita o número da porta.
`/defaultauthdb`	Opcional. O authentication database de autenticação a ser usado se a connection string incluir as credenciais de autenticação `username:password@` , mas não a opção `authSource` . Se você não incluir este componente, o cliente autenticará o usuário no banco de dados do `admin` . Também pode ser o banco de dados de aplicativo se e somente se a opção `database` não for especificada no array de configuração do banco de dados.
`?<options>`	Opcional. Uma string da query que especifica opções específicas de conexão como `<name>=<value>` pares. Consulte o guia Opções de conexão para obter uma descrição completa dessas opções.

O exemplo a seguir mostra um URI de conexão completo que especifica o protocolo, as credenciais, o nome do host, a porta e as opções de conexão:

mongodb://myUser:myPass123@localhost:27017/?w=majority&retryWrites=true

Para obter mais informações sobre connection strings, consulte Connection strings no manual manual do servidor.

Configuração da conexão do banco de dados Laravel

A integração do Laravel permite configurar sua conexão do banco de dados de dados MongoDB no arquivo de aplicação config/database.php Laravel. Você pode especificar os seguintes detalhes da conexão neste arquivo:

default, que especifica a conexão do banco de dados a ser usada quando não for especificado
connections, que contém informações de conexão do banco de dados para acessar um ou mais bancos de dados do seu aplicativo

Você pode usar o seguinte código no arquivo de configuração para definir a conexão padrão para uma entrada mongodb correspondente na array connections :

'default' => 'mongodb',

Para uma conexão do MongoDB database , você pode especificar os seguintes detalhes:

Contexto	Descrição
`driver`	Especifica o driver do banco de dados a ser usado para a conexão.
`dsn`	O nome da fonte de dados (DSN) que especifica o URI de conexão MongoDB.
`host`	Especifica o endereço de rede e a porta de um ou mais nós do MongoDB em uma implantação. Você pode usar essa configuração em vez da configuração `dsn`. Para especificar um único host, passe o nome do host e a porta como uma string, conforme mostrado no exemplo a seguir: `'host' => 'myhost.example.com:27017',` Para especificar vários hosts, passe-os em uma array conforme mostrado no exemplo a seguir:: `'host' => ['node1.example.com:27017', 'node2.example.com:27017', 'node3.example.com:27017'],` Esta opção não aceita hosts que usam o formato de conexão de lista de valores iniciais DNS.
`database`	Especifica o nome do banco de MongoDB database para ler e gravar.
`username`	Especifica a credencial de nome de usuário do banco de dados para autenticar com o MongoDB.
`password`	Especifica a credencial de senha do usuário do banco de dados para autenticar com MongoDB.
`options`	Especifica as opções de conexão a serem passadas ao MongoDB que determinam o comportamento da conexão. Para saber mais sobre as opções de conexão, consulte Opções de conexão e autenticação.
`driver_options`	Especifica opções específicas a serem passadas para a biblioteca PHP do MongoDB que determinam o comportamento do driver para essa conexão. Para saber mais sobre as opções de driver, consulte Opções de conexão de driver.

A integração com o Laravel aplica a configuração de conexão prefix aos nomes das coleções. A configuração de conexão prefix_indexes não é suportada.

Observação

Você pode especificar as seguintes configurações na configuração do dsn como parâmetros em sua connection string MongoDB em vez de itens de array:

host
username
password
options e driver_options, especificados pelo nome da opção

O exemplo a seguir mostra como você pode especificar os detalhes da conexão do MongoDB no item de array connections :

Exemplo de configuração de conexão do MongoDB config/database.php

'connections' => [    'mongodb' => [        'driver' => 'mongodb',        'dsn' => 'mongodb+srv//myUser:myPass123@sample.host/',        'database' => 'sample_mflix',        'options' => [            'w' => 'majority',        ],        'driver_options' => [            'serverApi' => 1,        ],    ],    // ...],

As seções a seguir fornecem maneiras comuns de especificar conexões MongoDB.

Exemplo de conexão

Esta seção mostra como configurar o DSN do seu aplicativo Laravel usando uma connection string do MongoDB Atlas.

Para adicionar seu DSN do MongoDB ao seu aplicativo Laravel, faça as seguintes alterações:

Adicione o DSN como uma variável de ambiente no arquivo de configuração de ambiente .env do seu projeto. Defina o valor da variável para sua connection string do Atlas.
Adicione uma entrada de conexão para sua conexão MongoDB na array connections do seu arquivo de configuração config/database.php . Defina o valor dsn da entrada de conexão para fazer referência à variável de ambiente que contém seu DSN.

Os seguintes exemplos mostram como especificar o "mongodb+srv://myUser:myPass123@mongodb0.example.com/" como a connection string nos arquivos de configuração relevantes:

Amostra de arquivo .env configuração do ambiente

DB_URI="mongodb+srv://myUser:myPass123@mongodb0.example.com/"

Exemplo de entrada de conexão config/database.php

'connections' => [    'mongodb' => [        'dsn' => env('DB_URI'), // uses the value of the DB_URI environment variable        'driver' => 'mongodb',        'database' => 'sample_mflix',        // ...    ],  // ...]

Dica

Para recuperar sua Atlas connection do string, siga a etapa Criar uma string connection do tutorial de Início rápido.

Outras maneiras de se conectar ao MongoDB

As seções seguintes mostram como conectar a uma única instância do servidor MongoDB ou a um conjunto de réplica não hospedado no MongoDB Atlas.

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

Esta seção mostra um exemplo de connection string que você pode usar ao executar um aplicativo Laravel e um servidor MongoDB na mesma máquina, como seu ambiente de desenvolvimento local.

Para conectar seu aplicativo a uma instância do MongoDB hospedada na mesma máquina, você deve concluir as seguintes tarefas:

Baixe, instale e execute o servidor MongoDB.
Obtenha o endereço IP e a porta na qual seu servidor MongoDB está sendo executado. Se você usar as configurações padrão de uma instalação local do servidor MongoDB, o endereço IP será 127.0.0.1 e a porta será 27017.
Configure sua conexão config/database.php para fazer referência à variável de ambiente DB_URI para o valor do dsn, conforme mostrado na seção Exemplo de conexão .

O exemplo a seguir mostra uma connection string de exemplo que você pode adicionar ao arquivo .env se o seu aplicativo se conectar a um servidor MongoDB em execução no endereço IP e porta padrão:

Amostra de arquivo .env configuração de ambiente para se conectar a um servidor MongoDB local.

DB_URI="mongodb://127.0.0.1:27017/";

Para saber como baixar e instalar o servidor MongoDB , consulte Instalar MongoDB Community Edition no manual do servidor MongoDB.

Conectar a um conjunto de réplicas

Um sistema do conjunto de réplicas MongoDB é um grupo de instâncias conectadas, ou nós, onde os nós armazenam o mesmo conjunto de dados. Esta configuração de instâncias fornece redundância de dados e alta disponibilidade de dados.

Para conectar a um sistema do conjunto de réplicas, especifique o nome do host e o número da porta de cada nó, separados por vírgulas, e o nome do conjunto de réplicas como o valor do parâmetro replicaSet na connection string.

Este exemplo, que mostra a connection string que você pode adicionar ao arquivo .env do seu aplicativo Laravel para se conectar a um conjunto de réplicas, usa os seguintes valores de amostra:

host1, host2 e host3 como os nomes de host dos nós MongoDB
27017 como a porta na qual o MongoDB é executado nesses hosts
myRS como o nome configurado do conjunto de réplicas
myUser e myPass123 como as credenciais de um utilizador de banco de dados

DB_URI="mongodb://myUser:myPass123@host1:27017,host2:27017,host3:27017/?replicaSet=myRS"

Ao se conectar a um conjunto de réplicas, a biblioteca que a integração do Laravel usa para gerenciar conexões com o MongoDB executa as seguintes ações, a menos que especificado de outra forma:

Descobre todos os membros do conjunto de réplicas quando recebe o endereço de qualquer membro.
Envia operações para o membro apropriado, como instruções para escrever no nó primário . Para saber mais sobre o conjunto de réplicas primário, consulte Conjunto de réplicas primário no manual do servidor MongoDB.

Dica

É necessário especificar apenas um host para se conectar a um conjunto de réplicas. No entanto, para garantir a conectividade quando o host selecionado não estiver disponível, forneça a lista completa de hosts.

Para saber mais sobre como configurar um conjunto de réplicas MongoDB , consulte Implementar um conjunto de réplicas no manual do servidor MongoDB.

Conexão direta

Para forçar a execução de operações em um nó específico em um conjunto de réplicas do MongoDB, especifique as informações de conexão do nó na connection string e o parâmetro directConnection com um valor true .

As conexões diretas incluem as seguintes limitações:

As connection strings de formato de conexão da lista de sementes de DNS não podem ser usadas.
As operações de gravação falham quando o host especificado não é o primary.
Quando o host não for o primary, você deverá especificar a preferência de leitura secondary nas opções de conexão. Para saber mais sobre essa limitação, consulte a entrada de preferência de leitura secundária no manual do servidor MongoDB.

O exemplo abaixo mostra a connection string que você pode adicionar ao arquivo .env do seu aplicativo Laravel para estabelecer uma conexão direta com um nó secundário em um conjunto de réplicas do MongoDB. O exemplo utiliza os seguintes valores de amostra:

host2 como o nome do host do nó secundário
27017 como a porta na qual o nó do MongoDB escuta

Amostra de arquivo .env configuração do ambiente para habilitar uma conexão direta

DB_URI="mongodb://host2:27017/?directConnection=true&readPreference=secondary"

Voltar

Começar

Opções de conexão