MongoDB

Come usare MongoDB in Laravel: installazione del driver, configurazione, modelli Eloquent, query builder, uso come cache e code.

​

Introduzione

MongoDB è uno dei database NoSQL documentali più popolari. Alte performance in scrittura (adatto ad analytics e IoT), alta disponibilità (replica set con failover automatico), scaling orizzontale (sharding) e un potente linguaggio di query (aggregazioni, ricerca full-text, query geospaziali).

Diversamente da un DB SQL, in MongoDB ogni record è un documento BSON (JSON binario). L’applicazione può leggere i dati come JSON.

Per usare MongoDB da Laravel consigliato il pacchetto ufficiale mongodb/laravel-mongodb. Fornisce una ricca integrazione con Eloquent e le funzionalità di Laravel.

​

Installazione

​

Estensione PHP MongoDB

Serve l’estensione mongodb. In Laravel Herd o php.new è già installata. Manualmente via PECL:

pecl install mongodb

Verifica che l’estensione sia attiva sia in CLI sia nel web server.

​

Avvio del server MongoDB

MongoDB Community Server per lo sviluppo. Vedi la guida ufficiale.

Con Docker:

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

In cloud usa MongoDB Atlas. Aggiungi il tuo IP all’access list.

​

Pacchetto laravel-mongodb

composer require mongodb/laravel-mongodb

​

Configurazione

​

Variabili d’ambiente

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

Con Atlas:

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

​

config/database.php

'connections' => [
    // ...

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

Puoi usare MySQL e MongoDB insieme: lascia default invariato e aggiungi la connessione mongodb.

​

Funzionalità principali

​

Modelli Eloquent

Estendi 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 è schemaless: nessuna migration.

​

CRUD

use App\Models\Article;

$article = Article::create([
    'title' => 'Introduzione a MongoDB',
    'body' => 'MongoDB è un database orientato ai documenti.',
    'tags' => ['nosql', 'mongodb', 'laravel'],
    'published_at' => now(),
]);

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

$article->update(['title' => 'MongoDB Rev.']);

$article->delete();

​

Array e documenti embedded

$article->push('tags', 'database');
$article->pull('tags', 'nosql');

$articles = Article::where('meta.author', 'Taylor')->get();

​

Query Builder

Vedi la documentazione query builder.

use Illuminate\Support\Facades\DB;

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

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

​

Cache driver

Usa TTL index. Vedi la documentazione.

config/cache.php:

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

CACHE_STORE=mongodb

​

Queue driver

Vedi la documentazione.

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

QUEUE_CONNECTION=mongodb

​

GridFS

composer require league/flysystem-gridfs

config/filesystems.php:

'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');

​

Vector Search

Usa MongoDB Atlas Vector Search. Vettorizza testo/immagini/audio e cerca per similarità.

Disponibile solo su MongoDB Atlas. Crea prima l’indice Vector Search.

use App\Models\Article;

$queryVector = getEmbedding('Cos\'è 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 (Scout)

Motore Scout per MongoDB, che usa MongoDB Atlas Search. Vedi la documentazione.

Solo con Atlas. La collection di indice è separata da quella dei modelli.

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);

​

Con MySQL

MySQL e MongoDB insieme: $connection specifica il target per modello.

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

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

Relazioni tra modelli MySQL e MongoDB: vedi Hybrid Relations.

​

Riepilogo

Checklist installazione

1. pecl install mongodb
2. Avvia MongoDB (locale, Docker o Atlas)
3. composer require mongodb/laravel-mongodb
4. Setta MONGODB_URI e MONGODB_DATABASE in .env
5. Aggiungi la connessione mongodb in config/database.php

MongoDB vs MySQL

Caratteristica	MongoDB	MySQL
Modello dati	Documenti (JSON/BSON)	Tabelle (righe/colonne)
Schema	Schemaless	Fisso
Scaling	Orizzontale facile	Verticale prevalente
Transazioni	Multidocumento (v4+)	ACID completo
Adatto a	Log, analytics, IoT, dati flessibili	Dati strutturati, relazioni complesse

Funzionalità e configurazione

Funzionalità	Dove configurarla
Modelli Eloquent	Estendi MongoDB\Laravel\Eloquent\Model
Query Builder	DB::connection('mongodb')->collection(...)
Cache	config/cache.php + CACHE_STORE=mongodb
Coda	config/queue.php + QUEUE_CONNECTION=mongodb
File	config/filesystems.php + GridFS
Vector Search	Model::query()->vectorSearch(...) (Atlas)
Full-text	SCOUT_DRIVER=mongodb + trait Searchable (Atlas)

​

Prossimi passi

Documentazione ufficiale laravel-mongodb

Reference completa

Quick start

Basi rapide di uso

Configurazione database

Le basi delle connessioni al database in Laravel

Introduzione a Eloquent

Uso base di Eloquent ORM