> ## 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

> Zo gebruik je MongoDB in je Laravel-applicatie. Van het installeren van de driver tot configuratie, Eloquent-models, de query builder en het gebruik als cache- en queue-driver.

## Introductie

[MongoDB](https://www.mongodb.com/resources/products/fundamentals/why-use-mongodb) is een van de populairste NoSQL-documentgeoriënteerde databases. Kenmerkend zijn de hoge schrijfprestaties (ideaal voor analytics en IoT), hoge beschikbaarheid (automatische failover via replica sets), horizontale schaalbaarheid (sharding) en een krachtige querytaal (aggregaties, full-text search en geospatiale query's).

Anders dan het rij-kolomformaat van SQL-databases is elk record in MongoDB een document in BSON-formaat (binaire JSON). Je applicatie kan deze data ophalen in JSON-formaat.

```mermaid theme={null}
flowchart LR
    A["Laravel<br>applicatie"] --> B["mongodb/laravel-mongodb<br>package"]
    B --> C["MongoDB PHP-driver"]
    C --> D["MongoDB-server"]

    subgraph features ["Belangrijkste toepassingen"]
        E["Eloquent-models"]
        F["Query builder"]
        G["Cache-driver"]
        H["Queue-driver"]
        I["GridFS-bestandsopslag"]
        J["Vector search"]
        K["Full-text search (Scout)"]
    end

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

<Info>
  Als je MongoDB met Laravel gebruikt, raden we de `mongodb/laravel-mongodb`-package aan, die officieel door MongoDB wordt onderhouden. Deze package biedt een rijke integratie met Eloquent en andere Laravel-features.
</Info>

## Installatie

### MongoDB PHP-driver

Om verbinding te maken met MongoDB heb je de `mongodb` PHP-extensie nodig. Gebruik je [Laravel Herd](https://herd.laravel.com) of `php.new`, dan is deze al geïnstalleerd. Handmatig installeren doe je met PECL:

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

Zie de [installatiegids voor de MongoDB PHP-extensie](https://www.php.net/manual/en/mongodb.installation.php) voor installatiedetails.

<Warning>
  Controleer of de `mongodb` PHP-extensie zowel voor de CLI als voor de webserver is ingeschakeld. De configuratie kan verschillen.
</Warning>

### De MongoDB-server starten

Voor lokale ontwikkeling kun je MongoDB Community Server gebruiken. Zie de [officiële installatiegids](https://docs.mongodb.com/manual/administration/install-community/) voor installatie op Windows, macOS, Linux en Docker.

**Met 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
```

Voor hosting in de cloud kun je [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) gebruiken. Om vanaf je lokale machine toegang te krijgen tot een Atlas-cluster moet je je eigen IP-adres toevoegen aan de IP-toegangslijst van het project.

### De laravel-mongodb-package installeren

Installeer de `mongodb/laravel-mongodb`-package met Composer:

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

## Configuratie

### Omgevingsvariabelen

Voeg de MongoDB-verbindingsgegevens toe aan je `.env`-bestand:

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

Gebruik je MongoDB Atlas, verander de connection string dan naar die van 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

Voeg een `mongodb`-verbinding toe aan de `connections`-array in `config/database.php`:

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

    // ... bestaande verbindingsconfiguratie ...

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

],
```

<Tip>
  Gebruik je een relationele database zoals MySQL tegelijk met MongoDB, dan hoef je alleen de `mongodb`-verbinding toe te voegen en kun je `default` gewoon laten staan. Je kunt per model van verbinding wisselen.
</Tip>

## Belangrijkste features

### Eloquent-models

Door te erven van `MongoDB\Laravel\Eloquent\Model` werk je met MongoDB op vrijwel dezelfde manier als met een gewoon Eloquent-model.

```php theme={null}
<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'articles'; // Collectionnaam (bij weglaten automatisch afgeleid van de klassenaam)

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

<Info>
  MongoDB is schemaloos, dus migrations zijn niet nodig. Zodra je een document opslaat, wordt de collection automatisch aangemaakt.
</Info>

#### Basis-CRUD-operaties

Je gebruikt dezelfde API als bij gewone Eloquent-models:

```php theme={null}
use App\Models\Article;

// Aanmaken
$article = Article::create([
    'title' => 'Inleiding tot MongoDB',
    'body' => 'MongoDB is een documentgeoriënteerde database.',
    'tags' => ['nosql', 'mongodb', 'laravel'],
    'published_at' => now(),
]);

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

// Bijwerken
$article->update(['title' => 'Inleiding tot MongoDB (herzien)']);

// Verwijderen
$article->delete();
```

#### Arrays en embedded documents

Arrays en embedded documents — de kracht van MongoDB — kun je direct gebruiken:

```php theme={null}
// Push naar een array-veld
$article->push('tags', 'database');

// Pull uit een array-veld
$article->pull('tags', 'nosql');

// Query op een embedded document
$articles = Article::where('meta.author', 'Taylor')->get();
```

### Query builder

Met de query builder van MongoDB kun je complexe query's schrijven. Zie de [laravel-mongodb query builder-documentatie](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/query-builder/) voor meer details.

```php theme={null}
use Illuminate\Support\Facades\DB;

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

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

### Cache-driver

De cache-driver van MongoDB gebruikt TTL-indexes om verlopen entries automatisch te verwijderen. Zie de [cache-driver-documentatie](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/cache/) voor meer details.

Voeg een store toe in `config/cache.php`:

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

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

],
```

Zet de cache-driver in `.env` op MongoDB:

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

### Queue-driver

Je kunt MongoDB gebruiken als queue-driver. Zie de [queue-driver-documentatie](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/queues/) voor meer details.

Voeg een verbinding toe in `config/queue.php`:

```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,
    ],

],
```

Zet de queue-verbinding in `.env` op MongoDB:

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

### Bestandsopslag met GridFS

Je kunt bestanden opslaan met GridFS van MongoDB. Hiervoor gebruik je de [GridFS-adapter voor Flysystem](https://flysystem.thephpleague.com/docs/adapter/gridfs/). Zie de [GridFS-documentatie](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/filesystems/) voor meer details.

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

Voeg een disk toe in `config/filesystems.php`:

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

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

],
```

```php theme={null}
use Illuminate\Support\Facades\Storage;

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

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

### Vector search

Met [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/fundamentals/vector-search/) kun je op basis van vector-embeddings zoeken naar vergelijkbare documenten. Je slaat data zoals tekst, afbeeldingen en audio op als vectoren en haalt vervolgens de documenten op die het dichtst bij de queryvector liggen — een zoekfunctie gericht op AI en machine learning.

<Info>
  Vector search is alleen beschikbaar op **MongoDB Atlas**. Het werkt niet met een lokale MongoDB Community Server of een self-hosted omgeving. Je moet vooraf een Vector Search-index aanmaken in de Atlas-console.
</Info>

De `vectorSearch`-methode is beschikbaar op de query builder:

```php theme={null}
use App\Models\Article;

// Genereer een embedding op basis van de querystring (bijv. via de OpenAI API)
$queryVector = getEmbedding('Wat is MongoDB'); // float[]-array

$results = Article::query()->vectorSearch(
    index: 'vector_index',   // Naam van de Atlas Vector Search-index
    path: 'embedding',       // Naam van het veld waarin de vector is opgeslagen
    queryVector: $queryVector,
    limit: 10,               // Aantal documenten dat wordt teruggegeven
    numCandidates: 100,      // Aantal kandidaten (opgeven bij ANN-zoeken)
);

// Elk document krijgt een vectorSearchScore
foreach ($results as $result) {
    echo $result->title . ': ' . $result->vectorSearchScore;
}
```

### Full-text search (Scout-engine)

Met de `mongodb` Scout-engine kun je de full-text search van [Laravel Scout](/nl/scout) gebruiken met MongoDB. Intern wordt **MongoDB Atlas Search** gebruikt, met ondersteuning voor fuzzy search en wildcard search. Zie de [Scout-engine-documentatie](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/scout/) voor meer details.

<Info>
  De MongoDB Scout-engine is eveneens alleen beschikbaar op **MongoDB Atlas**. De indexcollection van Scout moet een andere collection zijn dan die van het model. De `prefix`-instelling in `config/scout.php` (standaard de appnaam) wordt automatisch toegepast.
</Info>

Zet de Scout-driver in `.env` op `mongodb`:

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

Voeg de `Searchable`-trait toe aan je model:

```php theme={null}
use Laravel\Scout\Searchable;
use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    use Searchable;

    // Geef op welke velden in de zoekindex worden opgenomen
    public function toSearchableArray(): array
    {
        return [
            'title' => $this->title,
            'body'  => $this->body,
            'tags'  => $this->tags,
        ];
    }
}
```

Maak de Scout-index aan en importeer bestaande data:

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

Je zoekt met de standaard Scout-API:

```php theme={null}
// Full-text search
$results = Article::search('MongoDB Laravel')->get();

// Zoeken met filter
$results = Article::search('Query Builder')
    ->where('status', 'published')
    ->paginate(15);
```

## Gecombineerd gebruik met MySQL

In Laravel kun je MySQL en MongoDB tegelijk gebruiken. Je geeft per model de verbinding op met de `$connection`-property.

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

```php theme={null}
// Gewoon Eloquent-model dat MySQL gebruikt
class User extends \Illuminate\Database\Eloquent\Model
{
    protected $connection = 'mysql';
}

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

<Info>
  Wil je relaties tussen MySQL-models en MongoDB-models, raadpleeg dan [hybride relaties](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/eloquent-models/relationships/).
</Info>

## Samenvatting

<AccordionGroup>
  <Accordion title="Installatiechecklist">
    1. Installeer de PHP-extensie met `pecl install mongodb`
    2. Start de MongoDB-server (lokaal, via Docker of Atlas)
    3. Installeer de package met `composer require mongodb/laravel-mongodb`
    4. Stel `MONGODB_URI` en `MONGODB_DATABASE` in in `.env`
    5. Voeg de `mongodb`-verbinding toe aan `config/database.php`
  </Accordion>

  <Accordion title="MongoDB versus MySQL: wanneer gebruik je wat">
    | Eigenschap     | MongoDB                                              | MySQL                                     |
    | -------------- | ---------------------------------------------------- | ----------------------------------------- |
    | Datamodel      | Documenten (JSON/BSON)                               | Tabellen (rijen en kolommen)              |
    | Schema         | Schemaloos (flexibel)                                | Vast schema                               |
    | Schaalbaarheid | Eenvoudige horizontale schaling                      | Vooral verticale schaling                 |
    | Transacties    | Multi-document-ondersteuning (v4+)                   | Volledige ACID-ondersteuning              |
    | Geschikt voor  | Logs, analytics, IoT en data met flexibele structuur | Gestructureerde data en complexe relaties |
  </Accordion>

  <Accordion title="Welke feature configureer je waar">
    | Feature          | Configuratie                                                |
    | ---------------- | ----------------------------------------------------------- |
    | Eloquent-models  | Erf van `MongoDB\Laravel\Eloquent\Model`                    |
    | Query builder    | `DB::connection('mongodb')->collection(...)`                |
    | Cache            | `config/cache.php` + `CACHE_STORE=mongodb`                  |
    | Queue            | `config/queue.php` + `QUEUE_CONNECTION=mongodb`             |
    | Bestandsopslag   | `config/filesystems.php` + GridFS-adapter                   |
    | Vector search    | `Model::query()->vectorSearch(...)` (Atlas vereist)         |
    | Full-text search | `SCOUT_DRIVER=mongodb` + `Searchable`-trait (Atlas vereist) |
  </Accordion>
</AccordionGroup>

## Volgende stappen

<CardGroup cols={2}>
  <Card title="Officiële laravel-mongodb-documentatie" icon="book" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/">
    Gedetailleerde referentie voor alle features, waaronder Eloquent, de query builder en relaties
  </Card>

  <Card title="Quickstart" icon="rocket" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/quick-start/">
    Leer snel de basis van MongoDB met Laravel
  </Card>

  <Card title="Databaseconfiguratie" icon="database" href="/nl/database">
    De basis van databaseverbindingen configureren in Laravel
  </Card>

  <Card title="Introductie tot Eloquent" icon="table" href="/nl/eloquent">
    De basis van het Eloquent ORM
  </Card>
</CardGroup>


## Related topics

- [Zoeken](/nl/search.md)