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

# Gestire i fallimenti delle migrazioni con l'evento MigrationFailed

> Usa l'evento MigrationFailed di Laravel 13 per capire le informazioni di una migrazione fallita, i confini delle transazioni e la progettazione di monitoraggio e test.

Se vuoi monitorare i fallimenti delle migrazioni, ascolta `Illuminate\Database\Events\MigrationFailed`. Quando si verifica un'eccezione durante l'esecuzione di una singola migrazione, Laravel emette questo evento e poi rilancia l'eccezione.

Non è un meccanismo che riesegue automaticamente le migrazioni. È un evento che serve a passare a log e notifiche il nome della migrazione fallita, se è fallito `up` o `down`, e l'eccezione originale.

## Informazioni contenute nell'evento

`MigrationFailed` estende `MigrationEvent` ed espone i seguenti valori relativi a una singola migrazione.

| Proprietà | Tipo | Contenuto |
| - | - | - |
| `migration` | `Migration` | L'istanza della migrazione in esecuzione |
| `method` | `string` | Il metodo chiamato, di solito `up` o `down` |
| `name` | `string\|null` | Il nome della migrazione. Può essere `null` a seconda del percorso di esecuzione |
| `exception` | `Throwable` | L'eccezione che ha causato il fallimento |

Se registri anche `migration::class` oltre a `name`, puoi identificare la migrazione anche nei percorsi in cui il nome del file non è disponibile. Con `migration->getConnection()` puoi anche verificare il nome della connessione specificato esplicitamente dalla migrazione.

## Registrare un listener

Registra l'evento nel service provider della tua applicazione e passa al log un contesto strutturato e l'eccezione originale.

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

namespace App\Providers;

use Illuminate\Database\Events\MigrationFailed;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::listen(MigrationFailed::class, function (MigrationFailed $event): void {
            Log::error('Database migration failed.', [
                'migration' => $event->name,
                'class' => $event->migration::class,
                'method' => $event->method,
                'connection' => $event->migration->getConnection(),
                'exception' => $event->exception,
            ]);
        });
    }
}
```

Fai in modo che il listener si concentri sulla registrazione del fallimento, senza modificare lo schema né rieseguire migrazioni. Poiché l'eccezione originale viene rilanciata dopo l'evento, `php artisan migrate` e `php artisan migrate:rollback` terminano comunque con un errore.

## Ordine di emissione

Per una normale singola migrazione, il `Migrator` emette gli eventi nel seguente ordine.

```mermaid theme={null}
flowchart TD
    A["MigrationsStarted<br>Inizio del batch"] --> B["MigrationStarted<br>Inizio di una migrazione"]
    B --> C{"up / down riuscito?"}
    C -->|Successo| D["MigrationEnded<br>Migrazione completata"]
    D --> E["Migrazione successiva"]
    E --> F["MigrationsEnded<br>Batch completato"]
    C -->|Eccezione| G["MigrationFailed<br>Contiene l'eccezione"]
    G --> H["Rilanciare l'eccezione originale"]
```

`MigrationEnded` viene emesso solo quando l'esecuzione ha successo. Se l'elaborazione della migrazione, o un listener di un evento emesso durante l'esecuzione, lancia un'eccezione, si entra nella gestione delle eccezioni di `runMigration` e viene emesso `MigrationFailed`.

Inoltre, se l'eccezione viene rilanciata a metà di un batch, le migrazioni rimanenti non vengono eseguite. Per questo `MigrationsEnded` non viene necessariamente emesso per un batch fallito. Non gestire il completamento del batch e il fallimento con un unico evento.

## Rapporto con le transazioni

Quando lo Schema Grammar del database supporta le transazioni di schema e `withinTransaction` della migrazione è attivo, Laravel racchiude l'esecuzione in una transazione.

```php theme={null}
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('orders', function (Blueprint $table): void {
            $table->string('status');
        });
    }
};
```

Se l'elaborazione fallisce in questo percorso, `MigrationFailed` viene emesso dopo il rollback della transazione. Tuttavia, nei casi seguenti il database non può sempre annullare tutte le operazioni:

* Il database o lo Schema Grammar in uso non supporta le transazioni di schema
* La migrazione specifica `public $withinTransaction = false`
* Il database non tratta il DDL come transazionale

Quindi non concludere che lo schema sia tornato allo stato originale solo perché hai ricevuto questo evento. Nell'ambiente in cui si è verificato il fallimento, controlla lo schema effettivo e lo stato della tabella `migrations` prima del ripristino.

## Distinguere i fallimenti di `up` e `down`

Anche i fallimenti del rollback vengono notificati con lo stesso evento. Controlla `method` per separare destinatari delle notifiche e procedure operative tra applicazione e annullamento.

```php theme={null}
Event::listen(MigrationFailed::class, function (MigrationFailed $event): void {
    $operation = $event->method === 'down' ? 'rollback' : 'migrate';

    Log::critical('Migration operation failed.', [
        'operation' => $operation,
        'migration' => $event->name ?? $event->migration::class,
        'exception' => $event->exception,
    ]);
});
```

Quando `down` fallisce, l'eccezione si verifica prima che la migrazione venga rimossa dalla tabella `migrations`. Il `Migrator` esegue la rimozione solo dopo che `down` è terminato correttamente, quindi dopo un fallimento controlla sia lo schema effettivo sia il record.

## Confini di monitoraggio e notifiche

`MigrationFailed` viene elaborato in modo sincrono nel processo che ha eseguito il deploy o il comando Artisan manuale. Se metti la notifica in coda, puoi spostarne la consegna a un'elaborazione successiva senza nascondere il fallimento del comando di migrazione stesso.

Evita però di rieseguire la migrazione fallita dal listener. Rieseguirla mentre lo stesso comando non è ancora terminato complica i lock, il DDL applicato parzialmente e l'ordine del deploy. Se una riesecuzione è necessaria, correggi la causa, verifica lo stato ed eseguila come procedura operativa.

## Verificare l'evento nei test

Prepara una migrazione di test che fallisce e verifica che il comando Artisan fallisca e che l'evento contenga l'eccezione che l'ha causato. Non collocare le migrazioni di test dove possono essere trovate in produzione.

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

namespace Tests\Feature;

use Illuminate\Database\Events\MigrationFailed;
use Illuminate\Support\Facades\Event;
use RuntimeException;
use Tests\TestCase;

class MigrationFailureTest extends TestCase
{
    public function test_failed_migration_dispatches_event(): void
    {
        Event::fake([MigrationFailed::class]);

        $this->artisan('migrate', [
            '--path' => 'tests/Fixtures/migrations/2026_01_01_000000_fail.php',
        ])->assertFailed();

        Event::assertDispatched(MigrationFailed::class, function (MigrationFailed $event): bool {
            return $event->method === 'up'
                && $event->exception instanceof RuntimeException;
        });
    }
}
```

`Event::fake` registra gli eventi, quindi puoi testare separatamente dall'elaborazione reale delle notifiche dell'applicazione. Verifica la presenza del rollback, e che non resti DDL applicato parzialmente, in test di integrazione separati che usano il tuo database e il tuo Schema Grammar.

## Riepilogo

* `MigrationFailed` passa `migration`, `method`, `name` ed `exception` quando una singola migrazione fallisce.
* `MigrationEnded` viene emesso solo in caso di successo, e `MigrationsEnded` solo quando il batch viene completato fino alla fine.
* Il comportamento di transazioni e DDL varia a seconda del database, quindi non considerare l'evento come una garanzia di rollback.
* Limita i listener a monitoraggio e notifiche, ed esegui riesecuzioni e ripristino come procedura operativa dopo aver verificato la causa e lo schema.

## Fonti primarie consultate

* [Documentazione ufficiale di Laravel: eventi delle migrazioni](https://github.com/laravel/docs/blob/13.x/migrations.md#events)
* [Documentazione ufficiale di Laravel: listener di eventi](https://github.com/laravel/docs/blob/13.x/events.md#registering-events-and-listeners)
* [Framework 13.x: MigrationFailed](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Events/MigrationFailed.php)
* [Framework 13.x: MigrationEvent](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Events/MigrationEvent.php)
* [Framework 13.x: emissione degli eventi nel Migrator](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migrator.php#L435-L460)
* [Framework 13.x: classe base Migration](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migration.php)


## Related topics

- [Argomenti avanzati](https://kawax.biz/it/advanced/index.md)
- [Migration del database](https://kawax.biz/it/migrations.md)
- [Pubblicazione e aggiornamento delle migrazioni di un pacchetto](https://kawax.biz/it/advanced/package-migrations.md)
- [Telemetria](https://kawax.biz/it/packages/laravel-copilot-sdk/telemetry.md)
- [Sviluppare pacchetti con Testbench Workbench](https://kawax.biz/it/advanced/package-workbench.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.