Tutorial: Crie um serviço de backend usando o Laravel MongoDB

Visão geral

Neste tutorial, você cria um backend REST simples para um aplicativo front-end usando o Laravel MongoDB. O tutorial usa as funcionalidades de roteamento da API integradas do Laravel.

Pré-requisitos

Antes de iniciar este tutorial, você precisa do seguinte software instalado em seu ambiente de desenvolvimento:

Cluster MongoDB Atlas com dados de amostra carregados. Para saber como criar um cluster, consulte a etapa Criar uma implementação do MongoDB do guia Início rápido.
PHP.
Composer.
Extensão MongoDB PHP.
Um aplicativo de terminal e shell. Para usuários do MacOS, use o Terminal ou um aplicativo semelhante. Para usuários do Windows, use o PowerShell.

Passos

Criar um projeto Laravel .

Primeiro, crie um diretório de projeto do Laravel. Em seguida, execute o seguinte comando para criar um novo projeto Laravel chamado laraproject:

composer create-project laravel/laravel laraproject

Instale o Laravel MongoDB.

Para verificar se o Laravel MongoDB está em execução no servidor da web, adicione uma página da web ao seu site do Laravel. No seu projeto, navegue até /routes/web.php e adicione a seguinte rota:

Route::get('/info', function () {
    phpinfo();
});

Em seguida, execute o seguinte comando em seu shell para iniciar seu aplicação:

php artisan serve

Depois que o aplicação começar a ser executado, navegue até http://:127.0.0.1 8000/info para ver a página PHPinfo. Role para baixo ou procure a entrada mongodb para verificar se a extensão PHP do MongoDB está instalada.

Execute o seguinte comando em sua shell para instalar o Laravel MongoDB:

composer require mongodb/laravel-mongodb:^5.4

Configure sua conexão MongoDB .

Abra o arquivo config/database.php do seu projeto e atualize a array connections conforme mostrado no código a seguir:

'connections' => [
        'mongodb' => [
            'driver' => 'mongodb',
            'dsn' => '<connection string>',
            'database' => 'db',
        ],

Certifique-se de substituir o espaço reservado da string de conexão no código anterior pela sua string de conexão antes de executar o aplicação. Para saber como localizar sua string de conexão, consulte Criar uma connection string no guia de Início rápido.

Você também pode definir a conexão do banco de dados padrão. No topo do arquivo config/database.php, altere "padrão" para o seguinte:

'default' => 'mongodb',

O aplicação Laravel agora pode se conectar ao banco de dados do db em seu cluster MongoDB .

Crie um endpoint para ping do seu sistema.

Execute o seguinte comando shell para configurar o roteamento da API:

php artisan install:api

No arquivo routes/api.php recém-criado, adicione a seguinte rota:

// Add the DB use statement to the top of the file.
use Illuminate\Support\Facades\DB;
Route::get('/ping', function (Request $request) {
    $connection = DB::connection('mongodb');
    $msg = 'MongoDB is accessible!';
    try {
        $connection->command(['ping' => 1]);
    } catch (\Exception $e) {
        $msg = 'MongoDB is not accessible. Error: ' . $e->getMessage();
    }
    return ['msg' => $msg];
});

Recarregue o aplicação e verifique se http://:127.0.0.1 8000/api/ ping mostra a mensagem de ping bem-sucedida.

Criar modelos Eloquent.

O Laravel é integrado ao Eloquent, um ORM que abstrai o backend do banco de dados para que você possa se conectar a diferentes bancos de dados usando uma interface comum.

A Eloquent fornece uma classe Model para servir como a interface entre seu código e uma coleção específica. As instâncias das classes Model representam linhas de tabelas em bancos de dados relacionais. No MongoDB, eles são documentos na coleção.

Dica

Você pode definir campos preenchíveis em seus modelos Eloquent para impor um esquema de documento em seu aplicação e evitar erros como erros de digitação de nome. Para saber mais, consulte a seção Personalizar Atribuição de Massa do guia Classe de Modelo Eloquent.

Crie um modelo Eloquent chamado CustomerMongoDB executando o seguinte comando a partir da raiz do projeto :

php artisan make:model CustomerMongoDB

O Laravel cria a classe CustomerMongoDB no diretório /models. Por padrão, os modelos utilizam a conexão do banco de dados do default, mas você pode especificar qual conexão utilizar adicionando o membro do $connection à classe. Você também pode especificar o nome da coleção adicionando o membro $collection.

Certifique-se de incluir a instrução use para o modelo MongoDB Eloquent. Isso é necessário para definir _id como a chave primária.

Substitua o conteúdo do arquivo CustomerMongoDB.php pelo seguinte código:

use MongoDB\Laravel\Eloquent\Model;
class CustomerMongoDB extends Model
{
    // the selected database as defined in /config/database.php
    protected $connection = 'mongodb';
    // equivalent to $table for MySQL
    protected $collection = 'laracoll';
    // defines the schema for top-level properties (optional).
    protected $fillable = ['guid', 'first_name', 'family_name', 'email', 'address'];
}

Executar operações CRUD.

Após criar seus modelos, você pode executar operações de dados.

Crie a seguinte rota no seu arquivo api.php:

Route::get('/create_eloquent_mongo/', function (Request $request) {
    $success = CustomerMongoDB::create([
        'guid'=> 'cust_1111',
        'first_name'=> 'John',
        'family_name' => 'Doe',
        'email' => 'j.doe@gmail.com',
        'address' => '123 my street, my city, zip, state, country'
    ]);
});

Depois de inserir o documento, você pode recuperá-lo usando o método where(), conforme mostrado no código a seguir:

Route::get('/find_eloquent/', function (Request $request) {
    $customer = CustomerMongoDB::where('guid', 'cust_1111')->get();
});

O Eloquent permite que você encontre dados usando queries complexas com várias condições correspondentes.

Você também pode atualizar e excluir dados mostrados nas seguintes rotas:

Route::get('/update_eloquent/', function (Request $request) {
    $result = CustomerMongoDB::where('guid', 'cust_1111')->update( ['first_name' => 'Jimmy'] );
});
Route::get('/delete_eloquent/', function (Request $request) {
    $result = CustomerMongoDB::where('guid', 'cust_1111')->delete();
});

Neste ponto, seu serviço de back-end conectado ao MongoDB está em execução, mas o MongoDB fornece mais funcionalidades para dar suporte às suas operações.

Executar operações em dados aninhados.

O Laravel MongoDB oferece operações específicas do MongoDB para dados aninhados. No entanto, adicionar dados aninhados também é intuitivo sem usar os métodos embedsMany() e embedsOne().

Conforme mostrado na etapa anterior, você pode definir atributos de esquema de nível superior. No entanto, é mais complicado quando definir esses atributos se seus documentos incluírem arrays e documentos incorporados.

Você pode criar as estruturas de dados do modelo em PHP. No exemplo seguinte, o campo address é um tipo de objeto . O campo email é uma array de strings:

Route::get('/create_nested/', function (Request $request) {
    $message = "executed";
    $success = null;
    $address = new stdClass;
    $address->street = '123 my street name';
    $address->city = 'my city';
    $address->zip= '12345';
    $emails = ['j.doe@gmail.com', 'j.doe@work.com'];
    try {
        $customer = new CustomerMongoDB();
        $customer->guid = 'cust_2222';
        $customer->first_name = 'John';
        $customer->family_name= 'Doe';
        $customer->email= $emails;
        $customer->address= $address;
        $success = $customer->save(); // save() returns 1 or 0
    }
    catch (\Exception $e) {
        $message = $e->getMessage();
    }
    return ['msg' => $message, 'data' => $success];
});

Quando você acessa o endpoint /api/create_nested/, ele cria um documento no MongoDB:

{
  "_id": {...},
  "guid": "cust_2222",
  "first_name": "John",
  "family_name": "Doe",
  "email": [
    "j.doe@gmail.com",
    "j.doe@work.com"
  ],
  "address": {
    "street": "123 my street name",
    "city": "my city",
    "zip": "12345"
  },
  "updated_at": {
    "$date": "2025-05-27T17:38:28.793Z"
  },
  "created_at": {
    "$date": "2025-05-27T17:38:28.793Z"
  }
}

Use a MongoDB Query API.

O MongoDB fornece a API Query para queries otimizadas.

Você pode começar a construir uma consulta usando um objeto collection . O Eloquent expõe todos os recursos do banco de dados subjacente usando "queries brutas", que o Laravel envia para o banco de dados sem nenhum processamento do Eloquent Query Builder.

Você pode realizar uma query nativa bruta do MongoDB a partir do modelo, conforme mostrado no código a seguir:

$mongodbquery = ['guid' => 'cust_1111'];
// returns a "Illuminate\Database\Eloquent\Collection" Object
$results = CustomerMongoDB::whereRaw( $mongodbquery )->get();

Você também pode acessar o objeto de coleção nativo do MongoDB e executar uma query que retorna objetos como documentos ou cursores nativos do MongoDB :

$mongodbquery = ['guid' => 'cust_1111', ];
$mongodb_native_collection = DB::connection('mongodb')->getCollection('laracoll');
$document = $mongodb_native_collection->findOne( $mongodbquery );
$cursor = $mongodb_native_collection->find( $mongodbquery );

O seguinte código demonstra várias maneiras de realizar query:

Route::get('/find_native/', function (Request $request) {
    // a simple MongoDB query that looks for a customer based on the guid
    $mongodbquery = ['guid' => 'cust_2222'];
    // Option #1
    // =========
    // use Eloquent's whereRaw() function
    // returns a "Illuminate\Database\Eloquent\Collection" Object
    $results = CustomerMongoDB::whereRaw( $mongodbquery )->get();
    // Option #2 & #3
    // ==============
    // use the native MongoDB driver Collection object and the Query API
    $mdb_collection = DB::connection('mongodb')->getCollection('laracoll');
    // find the first document that matches the query
    $mdb_bsondoc = $mdb_collection->findOne( $mongodbquery ); // returns a "MongoDB\Model\BSONDocument" Object
    // to convert the MongoDB Document to a Laravel Model, use the Model's newFromBuilder() method
    $cust = new CustomerMongoDB();
    $one_doc = $cust->newFromBuilder((array) $mdb_bsondoc);
    // find all documents because you pass an empty query
    $mdb_cursor = $mdb_collection->find(); // returns a "MongoDB\Driver\Cursor" object
    $cust_array = array();
    foreach ($mdb_cursor->toArray() as $bson) {
        $cust_array[] = $cust->newFromBuilder( $bson );
    }
    return ['msg' => 'executed', 'whereraw' => $results, 'document' => $one_doc, 'cursor_array' => $cust_array];
});

O código abaixo demonstra como usar o método updateOne() para atualizar documentos:

Route::get('/update_native/', function (Request $request) {
    $mdb_collection = DB::connection('mongodb')->getCollection('laracoll');
    $match = ['guid' => 'cust_2222'];
    $update = ['$set' => ['first_name' => 'Henry', 'address.street' => '777 new street name'] ];
    $result = $mdb_collection->updateOne($match, $update );
    return ['msg' => 'executed', 'matched_docs' => $result->getMatchedCount(), 'modified_docs' => $result->getModifiedCount()];
});

O seguinte código demonstra como utilizar o método deleteOne() para excluir documentos:

Route::get('/delete_native/', function (Request $request) {
    $mdb_collection = DB::connection('mongodb')->getCollection('laracoll');
    $match = ['guid' => 'cust_2222'];
    $result = $mdb_collection->deleteOne($match );
    return ['msg' => 'executed', 'deleted_docs' =>
    $result->getDeletedCount() ];
});

Para saber mais sobre como realizar operações CRUD, consulte os guias Operações de gravação e Operações de leitura.

Use a estrutura de agregação .

Um pipeline de agregação é uma tarefa na estrutura de agregação do MongoDB. Você pode usar a framework de agregação para executar várias tarefas, como dashboards em tempo real e análise de big data.

Um pipeline de agregação consiste em vários estágios em que a saída de cada estágio é a entrada do estágio seguinte. Esta etapa utiliza o sample_mflix a partir dos conjuntos de dados de amostra do Atlas . O Laravel permite acessar vários bancos de dados do MongoDB no mesmo aplicativo, portanto, adicione a sample_mflix conexão de banco de dados database.php ao:

'mongodb_mflix' => [
            'driver' => 'mongodb',
            'dsn' => env('DB_URI'),
            'database' => 'sample_mflix',
        ],

Em seguida, crie o endpoint /aggregate/ da API e defina um agregação pipeline para recuperar dados da collection movies, calcular a classificação média do filme para cada gênero e retornar uma lista.

Route::get('/aggregate/', function (Request $request) {
    $mdb_collection = DB::connection('mongodb_mflix')->getCollection('movies');
    $stage0 = ['$unwind' => ['path' => '$genres']];
    $stage1 = ['$group' => ['_id' => '$genres', 'averageGenreRating' => ['$avg' => '$imdb.rating']]];
    $stage2 = ['$sort' => ['averageGenreRating' => -1]];
    $aggregation = [$stage0, $stage1, $stage2];
    $mdb_cursor = $mdb_collection->aggregate( $aggregation );
    return ['msg' => 'executed', 'data' => $mdb_cursor->toArray() ];
});

O Laravel MongoDB fornece o Construtor de Agregação para criar pipelines de agregação seguros por tipo diretamente de seus modelos. Recomendamos usar o construtor de agregação para executar agregações.

Use índices para otimizar o desempenho da query.

Você pode criar índices para dar suporte às suas queries e melhorar o desempenho. Para saber mais sobre como criar índices programaticamente, consulte a seção Gerenciar índices do guia Construtor de esquemas.

Conclusão

Neste tutorial, você aprenderá como criar um serviço de backend usando o Laravel e o MongoDB para um aplicação web de frontend. Este tutorial também mostra como usar o modelo de documento para melhorar a eficiência e a escalabilidade do banco de dados . Você pode usar o modelo de documento com a MongoDB Query API para criar aplicativos melhores com menos tempo de inatividade.

Você pode acessar o código completo deste tutorial no repositório laravel-mongodb-tutorial no GitHub.

Navegue pelo restante da documentação do Laravel MongoDB para saber mais sobre os recursos do Laravel MongoDB.

Voltar

Próximos passos

Exemplos de uso