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

# Mislukte migraties afhandelen met het MigrationFailed-event

> Gebruik het MigrationFailed-event van Laravel 13 om de gegevens van een mislukte migratie, transactiegrenzen en het ontwerp van monitoring en tests te begrijpen.

Wilt u mislukte migraties monitoren, luister dan naar `Illuminate\Database\Events\MigrationFailed`. Wanneer er tijdens het uitvoeren van een enkele migratie een exception optreedt, verzendt Laravel dit event en gooit daarna de exception opnieuw.

Dit is geen mechanisme dat migraties automatisch opnieuw uitvoert. Het event dient om de naam van de mislukte migratie, of `up` of `down` mislukte, en de oorspronkelijke exception door te geven aan logs en notificaties.

## Gegevens van het event

`MigrationFailed` erft van `MigrationEvent` en stelt de volgende waarden voor een enkele migratie beschikbaar.

| Eigenschap | Type | Inhoud |
| - | - | - |
| `migration` | `Migration` | De migratie-instantie die wordt uitgevoerd |
| `method` | `string` | De aangeroepen methode, meestal `up` of `down` |
| `name` | `string\|null` | De naam van de migratie. Afhankelijk van het uitvoeringspad `null` |
| `exception` | `Throwable` | De exception die de fout veroorzaakte |

Als u naast `name` ook `migration::class` vastlegt, kunt u de migratie identificeren, ook op paden waar de bestandsnaam niet beschikbaar is. Met `migration->getConnection()` kunt u ook de verbindingsnaam controleren die de migratie expliciet heeft opgegeven.

## Een listener registreren

Registreer het event in de service provider van uw applicatie en geef gestructureerde context en de oorspronkelijke exception door aan de log.

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

Laat de listener zich richten op het vastleggen van de fout en wijzig daarin niet het schema en voer geen migraties opnieuw uit. Omdat de oorspronkelijke exception na het event opnieuw wordt gegooid, eindigen `php artisan migrate` en `php artisan migrate:rollback` nog steeds met een fout.

## Volgorde van verzending

Bij een normale enkele migratie verzendt de `Migrator` de events in de volgende volgorde.

```mermaid theme={null}
flowchart TD
    A["MigrationsStarted<br>Batch start"] --> B["MigrationStarted<br>Enkele migratie start"]
    B --> C{"up / down geslaagd?"}
    C -->|Geslaagd| D["MigrationEnded<br>Enkele migratie voltooid"]
    D --> E["Volgende migratie"]
    E --> F["MigrationsEnded<br>Batch voltooid"]
    C -->|Exception| G["MigrationFailed<br>Bevat de exception"]
    G --> H["Oorspronkelijke exception opnieuw gooien"]
```

`MigrationEnded` wordt alleen verzonden als de uitvoering slaagt. Gooit de verwerking van de migratie, of een listener van een event dat tijdens de uitvoering werd verzonden, een exception, dan komt de uitvoering in de exceptionafhandeling van `runMigration` terecht en wordt `MigrationFailed` verzonden.

Wordt de exception halverwege een batch opnieuw gegooid, dan worden de resterende migraties niet uitgevoerd. Daarom wordt `MigrationsEnded` niet per se verzonden voor een mislukte batch. Behandel het voltooien van een batch en het mislukken niet met één en hetzelfde event.

## Relatie met transacties

Wanneer de Schema Grammar van de database schematransacties ondersteunt en `withinTransaction` van de migratie is ingeschakeld, omsluit Laravel de uitvoering met een transactie.

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

Mislukt de verwerking op dit pad, dan wordt `MigrationFailed` verzonden na de rollback van de transactie. In de volgende gevallen kan de database echter niet altijd alle bewerkingen terugdraaien:

* De gebruikte database of Schema Grammar ondersteunt geen schematransacties
* De migratie stelt `public $withinTransaction = false` in
* De database behandelt DDL niet als transactie

Concludeer dus niet alleen op basis van dit event dat het schema weer in de oorspronkelijke staat is. Controleer in de omgeving waar het misging het werkelijke schema en de staat van de tabel `migrations` voordat u herstelt.

## Fouten in `up` en `down` onderscheiden

Fouten bij een rollback worden via hetzelfde event gemeld. Controleer `method` om notificatiebestemmingen en operationele procedures te scheiden voor toepassen en terugdraaien.

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

Als `down` mislukt, treedt de exception op voordat de migratie uit de tabel `migrations` wordt verwijderd. De `Migrator` verwijdert de record pas nadat `down` met succes is voltooid. Controleer na een fout daarom zowel het werkelijke schema als de record.

## Grenzen van monitoring en notificaties

`MigrationFailed` wordt synchroon verwerkt in het proces dat de deployment of het handmatige Artisan-commando heeft uitgevoerd. Als u de notificatie in een queue plaatst, kunt u de bezorging ervan naar latere verwerking verplaatsen zonder de fout van het migratiecommando zelf te verbergen.

Vermijd echter dat u de mislukte migratie vanuit de listener opnieuw uitvoert. Opnieuw uitvoeren terwijl hetzelfde commando nog niet is beëindigd, maakt locks, gedeeltelijk toegepaste DDL en de volgorde van de deployment ingewikkelder. Is opnieuw uitvoeren nodig, los dan de oorzaak op, controleer de staat en voer het uit als operationele procedure.

## Het event in tests controleren

Bereid een test-migratie voor die mislukt en controleer dat het Artisan-commando mislukt en dat het event de veroorzakende exception bevat. Plaats test-migraties niet op een plek waar productie ze kan vinden.

```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` registreert events, zodat u los van de werkelijke notificatieverwerking van uw applicatie kunt testen. Of er een rollback plaatsvindt en of er geen DDL gedeeltelijk achterblijft, controleert u in aparte integratietests met uw database en Schema Grammar.

## Samenvatting

* `MigrationFailed` geeft bij het mislukken van een enkele migratie `migration`, `method`, `name` en `exception` door.
* `MigrationEnded` wordt alleen bij succes verzonden, en `MigrationsEnded` alleen als de batch volledig is voltooid.
* Het gedrag van transacties en DDL verschilt per database. Behandel het event daarom niet als garantie voor een rollback.
* Beperk listeners tot monitoring en notificaties, en voer herhalingen en herstel uit als operationele procedure nadat u de oorzaak en het schema hebt gecontroleerd.

## Geraadpleegde primaire bronnen

* [Officiële Laravel-documentatie: migratie-events](https://github.com/laravel/docs/blob/13.x/migrations.md#events)
* [Officiële Laravel-documentatie: event listeners](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: verzenden van events in de Migrator](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migrator.php#L435-L460)
* [Framework 13.x: basisklasse Migration](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migration.php)


## Related topics

- [Databasemigraties](https://kawax.biz/nl/migrations.md)
- [Streaming events](https://kawax.biz/nl/packages/laravel-copilot-sdk/streaming-events.md)
- [Events](https://kawax.biz/nl/packages/laravel-copilot-sdk/events.md)
- [Geavanceerde onderwerpen](https://kawax.biz/nl/advanced/index.md)
- [Laravel-updates van april 2026](https://kawax.biz/nl/blog/changelog/202604.md)


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