MongoDB - Knowledge of Laravel

Introductie

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.

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.

Installatie

MongoDB PHP-driver

Om verbinding te maken met MongoDB heb je de mongodb PHP-extensie nodig. Gebruik je Laravel Herd of php.new, dan is deze al geïnstalleerd. Handmatig installeren doe je met PECL:

pecl install mongodb

Zie de installatiegids voor de MongoDB PHP-extensie voor installatiedetails.

Controleer of de mongodb PHP-extensie zowel voor de CLI als voor de webserver is ingeschakeld. De configuratie kan verschillen.

De MongoDB-server starten

Voor lokale ontwikkeling kun je MongoDB Community Server gebruiken. Zie de officiële installatiegids voor installatie op Windows, macOS, Linux en Docker. Met 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

Voor hosting in de cloud kun je MongoDB 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:

composer require mongodb/laravel-mongodb

Configuratie

Omgevingsvariabelen

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

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

Gebruik je MongoDB Atlas, verander de connection string dan naar die van Atlas:

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:

'connections' => [

    // ... bestaande verbindingsconfiguratie ...

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

],

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.

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

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',
    ];
}

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

Basis-CRUD-operaties

Je gebruikt dezelfde API als bij gewone Eloquent-models:

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:

// 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 voor meer details.

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 voor meer details. Voeg een store toe in config/cache.php:

'stores' => [

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

],

Zet de cache-driver in .env op MongoDB:

CACHE_STORE=mongodb

Queue-driver

Je kunt MongoDB gebruiken als queue-driver. Zie de queue-driver-documentatie voor meer details. Voeg een verbinding toe in config/queue.php:

'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:

QUEUE_CONNECTION=mongodb

Bestandsopslag met GridFS

Je kunt bestanden opslaan met GridFS van MongoDB. Hiervoor gebruik je de GridFS-adapter voor Flysystem. Zie de GridFS-documentatie voor meer details.

composer require league/flysystem-gridfs

Voeg een disk toe in config/filesystems.php:

'disks' => [

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

],

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

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.

De vectorSearch-methode is beschikbaar op de query builder:

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 gebruiken met MongoDB. Intern wordt MongoDB Atlas Search gebruikt, met ondersteuning voor fuzzy search en wildcard search. Zie de Scout-engine-documentatie voor meer details.

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.

Zet de Scout-driver in .env op mongodb:

SCOUT_DRIVER=mongodb

Voeg de Searchable-trait toe aan je model:

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:

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

Je zoekt met de standaard Scout-API:

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

// 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';
}

Wil je relaties tussen MySQL-models en MongoDB-models, raadpleeg dan hybride relaties.

Samenvatting

Installatiechecklist

Installeer de PHP-extensie met pecl install mongodb
Start de MongoDB-server (lokaal, via Docker of Atlas)
Installeer de package met composer require mongodb/laravel-mongodb
Stel MONGODB_URI en MONGODB_DATABASE in in .env
Voeg de mongodb-verbinding toe aan config/database.php

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

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)

Volgende stappen

Officiële laravel-mongodb-documentatie

Gedetailleerde referentie voor alle features, waaronder Eloquent, de query builder en relaties

Quickstart

Leer snel de basis van MongoDB met Laravel

Databaseconfiguratie

De basis van databaseverbindingen configureren in Laravel

Introductie tot Eloquent

De basis van het Eloquent ORM

​Introductie

​Installatie

​MongoDB PHP-driver

​De MongoDB-server starten

​De laravel-mongodb-package installeren

​Configuratie

​Omgevingsvariabelen

​config/database.php

​Belangrijkste features

​Eloquent-models

​Basis-CRUD-operaties

​Arrays en embedded documents

​Query builder

​Cache-driver

​Queue-driver

​Bestandsopslag met GridFS

​Vector search

​Full-text search (Scout-engine)

​Gecombineerd gebruik met MySQL

​Samenvatting

​Volgende stappen

Officiële laravel-mongodb-documentatie

Quickstart

Databaseconfiguratie

Introductie tot Eloquent

Introductie

Installatie

MongoDB PHP-driver

De MongoDB-server starten

De laravel-mongodb-package installeren

Configuratie

Omgevingsvariabelen

config/database.php

Belangrijkste features

Eloquent-models

Basis-CRUD-operaties

Arrays en embedded documents

Query builder

Cache-driver

Queue-driver

Bestandsopslag met GridFS

Vector search

Full-text search (Scout-engine)

Gecombineerd gebruik met MySQL

Samenvatting

Volgende stappen