MongoDB

Utiliser MongoDB avec Laravel : installation du driver, configuration, modèles Eloquent, query builder, cache et driver de queue.

​

Introduction

MongoDB est l’une des bases NoSQL orientées documents les plus populaires. Ses atouts : hautes performances d’écriture (idéal pour l’analytique / IoT), haute disponibilité (réplication + failover), scalabilité horizontale (sharding), langage de requête puissant (aggregation, recherche plein-texte, géospatial).

Contrairement aux bases relationnelles, chaque enregistrement MongoDB est un document BSON (JSON binaire) que l’application manipule en JSON.

Le package mongodb/laravel-mongodb, maintenu officiellement par MongoDB, est recommandé. Il offre une intégration riche avec Eloquent et les autres composants Laravel.

​

Installation

​

Driver PHP MongoDB

Nécessite l’extension PHP mongodb. Elle est déjà présente avec Laravel Herd et php.new. Sinon, via PECL :

pecl install mongodb

Voir le guide d’installation officiel.

Vérifiez que l’extension mongodb est active côté CLI et côté serveur web (configurations parfois séparées).

​

Démarrer un serveur MongoDB

MongoDB Community Server pour le local. Voir le guide d’installation.

Avec Docker :

# docker-compose.yml
services:
  mongodb:
    image: mongo:8
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: password
      MONGO_INITDB_DATABASE: laravel_app
    volumes:
      - mongodb_data:/data/db

volumes:
  mongodb_data:

docker compose up -d

Pour l’hébergement cloud, MongoDB Atlas. Pensez à ajouter votre IP à la liste d’accès du projet.

​

Installer laravel-mongodb

composer require mongodb/laravel-mongodb

​

Configuration

​

Variables d’environnement

MONGODB_URI="mongodb://localhost:27017"
MONGODB_DATABASE="laravel_app"

Pour Atlas :

MONGODB_URI="mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<dbname>?retryWrites=true&w=majority"
MONGODB_DATABASE="laravel_app"

​

config/database.php

Ajoutez la connexion mongodb.

'connections' => [

    // ... connexions existantes ...

    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => env('MONGODB_URI', 'mongodb://localhost:27017'),
        'database' => env('MONGODB_DATABASE', 'laravel_app'),
    ],

],

Vous pouvez utiliser MySQL et MongoDB en parallèle : laissez default sur MySQL, ajoutez simplement la connexion mongodb. Chaque modèle choisit sa connexion.

​

Fonctionnalités

​

Modèles Eloquent

Héritez de MongoDB\Laravel\Eloquent\Model.

<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'articles';

    protected $fillable = [
        'title',
        'body',
        'tags',
        'published_at',
    ];
}

MongoDB étant schémaless, aucune migration n’est nécessaire. La collection est créée à la première écriture.

​

CRUD

Même API qu’Eloquent classique.

use App\Models\Article;

// Création
$article = Article::create([
    'title' => 'Introduction à MongoDB',
    'body' => 'MongoDB est une base orientée document.',
    'tags' => ['nosql', 'mongodb', 'laravel'],
    'published_at' => now(),
]);

// Lecture
$article = Article::find('64f1a2b3c4d5e6f7a8b9c0d1');
$articles = Article::where('tags', 'nosql')->get();

// Mise à jour
$article->update(['title' => 'MongoDB : édition révisée']);

// Suppression
$article->delete();

​

Tableaux / documents embarqués

// Ajouter à un tableau
$article->push('tags', 'database');

// Retirer d'un tableau
$article->pull('tags', 'nosql');

// Requête sur document embarqué
$articles = Article::where('meta.author', 'Taylor')->get();

​

Query Builder

Voir la documentation query builder de laravel-mongodb.

use Illuminate\Support\Facades\DB;

// Requête de base
$articles = DB::connection('mongodb')
    ->collection('articles')
    ->where('tags', 'laravel')
    ->orderBy('published_at', 'desc')
    ->limit(10)
    ->get();

// Pipeline d'agrégation
$stats = DB::connection('mongodb')
    ->collection('orders')
    ->raw(function ($collection) {
        return $collection->aggregate([
            ['$group' => ['_id' => '$status', 'total' => ['$sum' => '$amount']]],
            ['$sort' => ['total' => -1]],
        ]);
    });

​

Driver de cache

Utilise des index TTL pour la purge automatique. Voir la documentation cache.

Ajoutez le store :

'stores' => [

    'mongodb' => [
        'driver' => 'mongodb',
        'connection' => 'mongodb',
        'collection' => 'cache',
    ],

],

Puis :

CACHE_STORE=mongodb

​

Driver de queue

Voir la documentation queue.

'connections' => [

    'mongodb' => [
        'driver' => 'mongodb',
        'connection' => 'mongodb',
        'collection' => 'jobs',
        'queue' => env('MONGODB_QUEUE', 'default'),
        'retry_after' => (int) env('MONGODB_QUEUE_RETRY_AFTER', 90),
        'after_commit' => false,
    ],

],

QUEUE_CONNECTION=mongodb

​

Stockage GridFS

Stockage de fichiers via GridFS avec l’adaptateur Flysystem. Voir la documentation.

composer require league/flysystem-gridfs

'disks' => [

    'gridfs' => [
        'driver' => 'gridfs',
        'connection' => 'mongodb',
        'database' => env('MONGODB_DATABASE', 'laravel_app'),
    ],

],

use Illuminate\Support\Facades\Storage;

Storage::disk('gridfs')->put('file.pdf', $contents);

$contents = Storage::disk('gridfs')->get('file.pdf');

​

Recherche vectorielle

MongoDB Atlas Vector Search permet la recherche par similarité sur des embeddings.

Uniquement sur MongoDB Atlas. Créez au préalable un index Vector Search dans la console Atlas.

use App\Models\Article;

// Génère l'embedding via un service (OpenAI, etc.)
$queryVector = getEmbedding('Qu\'est-ce que MongoDB');

$results = Article::query()->vectorSearch(
    index: 'vector_index',
    path: 'embedding',
    queryVector: $queryVector,
    limit: 10,
    numCandidates: 100,
);

foreach ($results as $result) {
    echo $result->title . ': ' . $result->vectorSearchScore;
}

​

Full text (moteur Scout)

Le moteur mongodb pour Laravel Scout s’appuie sur MongoDB Atlas Search (fuzzy, wildcard…). Voir la documentation.

Uniquement sur MongoDB Atlas. Utilisez une collection distincte pour l’index — prefix de config/scout.php (par défaut le nom de l’app) s’applique automatiquement.

SCOUT_DRIVER=mongodb

use Laravel\Scout\Searchable;
use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    use Searchable;

    public function toSearchableArray(): array
    {
        return [
            'title' => $this->title,
            'body'  => $this->body,
            'tags'  => $this->tags,
        ];
    }
}

php artisan scout:index articles
php artisan scout:import "App\Models\Article"

$results = Article::search('MongoDB Laravel')->get();

$results = Article::search('query builder')
    ->where('status', 'published')
    ->paginate(15);

​

Coexistence avec MySQL

Utilisez les deux en simultané en spécifiant $connection sur chaque modèle.

class User extends \Illuminate\Database\Eloquent\Model
{
    protected $connection = 'mysql';
}

class Article extends \MongoDB\Laravel\Eloquent\Model
{
    protected $connection = 'mongodb';
}

Pour des relations entre modèles MySQL et MongoDB, voir les relations hybrides.

​

Récapitulatif

Checklist d'installation

1. pecl install mongodb (extension PHP)
2. Démarrer un serveur MongoDB (local, Docker, ou Atlas)
3. composer require mongodb/laravel-mongodb
4. Renseigner MONGODB_URI et MONGODB_DATABASE dans .env
5. Ajouter la connexion mongodb dans config/database.php

MongoDB vs MySQL

Caractéristique	MongoDB	MySQL
Modèle	Document JSON/BSON	Table (lignes/colonnes)
Schéma	Sans schéma (flexible)	Fixe
Scaling	Horizontal simple	Vertical majoritaire
Transactions	Multi-documents (v4+)	ACID complet
Usage	Logs, analytique, IoT, structures flexibles	Données structurées, relations complexes

Points de configuration

Fonctionnalité	Configuration
Modèles Eloquent	Hériter de MongoDB\Laravel\Eloquent\Model
Query Builder	DB::connection('mongodb')->collection(...)
Cache	config/cache.php + CACHE_STORE=mongodb
Queue	config/queue.php + QUEUE_CONNECTION=mongodb
Fichiers	config/filesystems.php + adaptateur GridFS
Vector search	Model::query()->vectorSearch(...) (Atlas requis)
Full text	SCOUT_DRIVER=mongodb + trait Searchable (Atlas requis)

​

Prochaines étapes

Documentation officielle laravel-mongodb

Référence complète Eloquent, Query Builder, relations, etc.

Quick Start

Prise en main rapide de Laravel + MongoDB.

Configuration de base de données

Bases des connexions DB dans Laravel.

Introduction à Eloquent

Fondamentaux de l’ORM Eloquent.