> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB

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

## Introduction

[MongoDB](https://www.mongodb.com/resources/products/fundamentals/why-use-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.

```mermaid theme={null}
flowchart LR
    A["Application<br>Laravel"] --> B["Package<br>mongodb/laravel-mongodb"]
    B --> C["Driver PHP MongoDB"]
    C --> D["Serveur MongoDB"]

    subgraph features ["Usages"]
        E["Modèles Eloquent"]
        F["Query Builder"]
        G["Cache"]
        H["Queue"]
        I["Stockage GridFS"]
        J["Recherche vectorielle"]
        K["Full text (Scout)"]
    end

    B --> E
    B --> F
    B --> G
    B --> H
    B --> I
    B --> J
    B --> K
```

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

## Installation

### Driver PHP MongoDB

Nécessite l'extension PHP `mongodb`. Elle est déjà présente avec [Laravel Herd](https://herd.laravel.com) et `php.new`. Sinon, via PECL :

```shell theme={null}
pecl install mongodb
```

Voir le [guide d'installation officiel](https://www.php.net/manual/fr/mongodb.installation.php).

<Warning>
  Vérifiez que l'extension `mongodb` est active côté CLI **et** côté serveur web (configurations parfois séparées).
</Warning>

### Démarrer un serveur MongoDB

MongoDB Community Server pour le local. Voir le [guide d'installation](https://docs.mongodb.com/manual/administration/install-community/).

**Avec Docker :**

```yaml theme={null}
# 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:
```

```shell theme={null}
docker compose up -d
```

Pour l'hébergement cloud, [MongoDB Atlas](https://www.mongodb.com/cloud/atlas). Pensez à ajouter votre IP à la liste d'accès du projet.

### Installer laravel-mongodb

```shell theme={null}
composer require mongodb/laravel-mongodb
```

## Configuration

### Variables d'environnement

```ini theme={null}
MONGODB_URI="mongodb://localhost:27017"
MONGODB_DATABASE="laravel_app"
```

Pour Atlas :

```ini theme={null}
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`.

```php theme={null}
'connections' => [

    // ... connexions existantes ...

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

],
```

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

## Fonctionnalités

### Modèles Eloquent

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

```php theme={null}
<?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',
    ];
}
```

<Info>
  MongoDB étant schémaless, aucune migration n'est nécessaire. La collection est créée à la première écriture.
</Info>

#### CRUD

Même API qu'Eloquent classique.

```php theme={null}
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

```php theme={null}
// 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](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/query-builder/).

```php theme={null}
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](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/cache/).

Ajoutez le store :

```php theme={null}
'stores' => [

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

],
```

Puis :

```ini theme={null}
CACHE_STORE=mongodb
```

### Driver de queue

Voir la [documentation queue](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/queues/).

```php theme={null}
'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,
    ],

],
```

```ini theme={null}
QUEUE_CONNECTION=mongodb
```

### Stockage GridFS

Stockage de fichiers via GridFS avec l'[adaptateur Flysystem](https://flysystem.thephpleague.com/docs/adapter/gridfs/). Voir la [documentation](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/filesystems/).

```shell theme={null}
composer require league/flysystem-gridfs
```

```php theme={null}
'disks' => [

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

],
```

```php theme={null}
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](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/fundamentals/vector-search/) permet la recherche par similarité sur des embeddings.

<Info>
  Uniquement sur **MongoDB Atlas**. Créez au préalable un index Vector Search dans la console Atlas.
</Info>

```php theme={null}
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](/fr/scout) s'appuie sur **MongoDB Atlas Search** (fuzzy, wildcard…). Voir la [documentation](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/scout/).

<Info>
  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.
</Info>

```ini theme={null}
SCOUT_DRIVER=mongodb
```

```php theme={null}
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,
        ];
    }
}
```

```shell theme={null}
php artisan scout:index articles
php artisan scout:import "App\Models\Article"
```

```php theme={null}
$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.

```mermaid theme={null}
flowchart TD
    A["Application Laravel"] --> B["UserController"]
    A --> C["ArticleController"]
    B --> D["User\n$connection = 'mysql'"]
    C --> E["Article\n$connection = 'mongodb'"]
    D --> F["MySQL"]
    E --> G["MongoDB"]
```

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

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

<Info>
  Pour des relations entre modèles MySQL et MongoDB, voir les [relations hybrides](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/eloquent-models/relationships/).
</Info>

## Récapitulatif

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="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) |
  </Accordion>
</AccordionGroup>

## Prochaines étapes

<CardGroup cols={2}>
  <Card title="Documentation officielle laravel-mongodb" icon="book" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/">
    Référence complète Eloquent, Query Builder, relations, etc.
  </Card>

  <Card title="Quick Start" icon="rocket" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/quick-start/">
    Prise en main rapide de Laravel + MongoDB.
  </Card>

  <Card title="Configuration de base de données" icon="database" href="/fr/database">
    Bases des connexions DB dans Laravel.
  </Card>

  <Card title="Introduction à Eloquent" icon="table" href="/fr/eloquent">
    Fondamentaux de l'ORM Eloquent.
  </Card>
</CardGroup>


## Related topics

- [Recherche](/fr/search.md)