MongoDB - Knowledge of Laravel

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

pecl install mongodb (extension PHP)
Démarrer un serveur MongoDB (local, Docker, ou Atlas)
composer require mongodb/laravel-mongodb
Renseigner MONGODB_URI et MONGODB_DATABASE dans .env
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.

​Introduction

​Installation

​Driver PHP MongoDB

​Démarrer un serveur MongoDB

​Installer laravel-mongodb

​Configuration

​Variables d’environnement

​config/database.php

​Fonctionnalités

​Modèles Eloquent

​CRUD

​Tableaux / documents embarqués

​Query Builder

​Driver de cache

​Driver de queue

​Stockage GridFS

​Recherche vectorielle

​Full text (moteur Scout)

​Coexistence avec MySQL

​Récapitulatif

​Prochaines étapes

Documentation officielle laravel-mongodb

Quick Start

Configuration de base de données

Introduction à Eloquent

Introduction

Installation

Driver PHP MongoDB

Démarrer un serveur MongoDB

Installer laravel-mongodb

Configuration

Variables d’environnement

`config/database.php`

Fonctionnalités

Modèles Eloquent

CRUD

Tableaux / documents embarqués

Query Builder

Driver de cache

Driver de queue

Stockage GridFS

Recherche vectorielle

Full text (moteur Scout)

Coexistence avec MySQL

Récapitulatif

Prochaines étapes