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

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

## Introduzione

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

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

    subgraph features ["Usi principali"]
        E["Modelli Eloquent"]
        F["Query Builder"]
        G["Cache driver"]
        H["Queue driver"]
        I["File storage con GridFS"]
        J["Vector Search"]
        K["Ricerca full-text (Scout)"]
    end

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

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

## Installazione

### Estensione PHP MongoDB

Serve l'estensione `mongodb`. In [Laravel Herd](https://herd.laravel.com) o `php.new` è già installata. Manualmente via PECL:

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

<Warning>
  Verifica che l'estensione sia attiva sia in CLI sia nel web server.
</Warning>

### Avvio del server MongoDB

MongoDB Community Server per lo sviluppo. Vedi la [guida ufficiale](https://docs.mongodb.com/manual/administration/install-community/).

**Con Docker:**

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

In cloud usa [MongoDB Atlas](https://www.mongodb.com/cloud/atlas). Aggiungi il tuo IP all'access list.

### Pacchetto laravel-mongodb

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

## Configurazione

### Variabili d'ambiente

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

Con 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

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

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

<Tip>
  Puoi usare MySQL e MongoDB insieme: lascia `default` invariato e aggiungi la connessione `mongodb`.
</Tip>

## Funzionalità principali

### Modelli Eloquent

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

#### CRUD

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

```php theme={null}
$article->push('tags', 'database');
$article->pull('tags', 'nosql');

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

### Query Builder

Vedi la [documentazione query builder](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/query-builder/).

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

`config/cache.php`:

```php theme={null}
'stores' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'connection' => 'mongodb',
        'collection' => 'cache',
    ],
],
```

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

### Queue driver

Vedi la [documentazione](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/queues/).

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

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

### GridFS

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

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

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

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

### Vector Search

Usa [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/fundamentals/vector-search/). Vettorizza testo/immagini/audio e cerca per similarità.

<Info>
  Disponibile solo su **MongoDB Atlas**. Crea prima l'indice Vector Search.
</Info>

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

<Info>
  Solo con **Atlas**. La collection di indice è separata da quella dei modelli.
</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);
```

## Con MySQL

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

```mermaid theme={null}
flowchart TD
    A["App 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>
  Relazioni tra modelli MySQL e MongoDB: vedi [Hybrid Relations](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/eloquent-models/relationships/).
</Info>

## Riepilogo

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

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

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

## Prossimi passi

<CardGroup cols={2}>
  <Card title="Documentazione ufficiale laravel-mongodb" icon="book" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/">
    Reference completa
  </Card>

  <Card title="Quick start" icon="rocket" href="https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/quick-start/">
    Basi rapide di uso
  </Card>

  <Card title="Configurazione database" icon="database" href="/it/database">
    Le basi delle connessioni al database in Laravel
  </Card>

  <Card title="Introduzione a Eloquent" icon="table" href="/it/eloquent">
    Uso base di Eloquent ORM
  </Card>
</CardGroup>


## Related topics

- [Ricerca](/it/search.md)