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

# Gérer les échecs de migration avec l'événement MigrationFailed

> Utilisez l'événement MigrationFailed de Laravel 13 pour comprendre les informations d'une migration échouée, les limites des transactions et la conception de la surveillance et des tests.

Pour surveiller les échecs de migration, écoutez `Illuminate\Database\Events\MigrationFailed`. Lorsqu'une exception survient pendant l'exécution d'une migration individuelle, Laravel émet cet événement puis relance l'exception.

Il ne s'agit pas d'un mécanisme qui réexécute automatiquement les migrations. Cet événement sert à transmettre aux logs et aux notifications le nom de la migration échouée, l'indication que c'est `up` ou `down` qui a échoué, et l'exception d'origine.

## Informations portées par l'événement

`MigrationFailed` hérite de `MigrationEvent` et expose les valeurs suivantes pour une migration individuelle.

| Propriété | Type | Contenu |
| - | - | - |
| `migration` | `Migration` | L'instance de migration exécutée |
| `method` | `string` | La méthode appelée, généralement `up` ou `down` |
| `name` | `string\|null` | Le nom de la migration. Peut être `null` selon le chemin d'exécution |
| `exception` | `Throwable` | L'exception à l'origine de l'échec |

Si vous enregistrez `migration::class` en plus de `name`, vous pouvez identifier la migration même sur les chemins où le nom du fichier n'est pas disponible. Avec `migration->getConnection()`, vous pouvez aussi vérifier le nom de connexion que la migration a spécifié explicitement.

## Enregistrer un listener

Enregistrez l'événement dans le service provider de votre application et transmettez au log un contexte structuré et l'exception d'origine.

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

Limitez le listener à l'enregistrement de l'échec, sans modifier le schéma ni réexécuter de migrations. Comme l'exception d'origine est relancée après l'événement, `php artisan migrate` et `php artisan migrate:rollback` se terminent toujours en échec.

## Ordre d'émission

Pour une migration individuelle normale, le `Migrator` émet les événements dans l'ordre suivant.

```mermaid theme={null}
flowchart TD
    A["MigrationsStarted<br>Début du lot"] --> B["MigrationStarted<br>Début d'une migration"]
    B --> C{"up / down réussi ?"}
    C -->|Succès| D["MigrationEnded<br>Migration terminée"]
    D --> E["Migration suivante"]
    E --> F["MigrationsEnded<br>Lot terminé"]
    C -->|Exception| G["MigrationFailed<br>Contient l'exception"]
    G --> H["Relancer l'exception d'origine"]
```

`MigrationEnded` n'est émis que si l'exécution réussit. Si le traitement de la migration, ou un listener d'un événement émis pendant l'exécution, lance une exception, l'exécution passe dans la gestion d'exceptions de `runMigration` et `MigrationFailed` est émis.

Par ailleurs, si l'exception est relancée au milieu d'un lot, les migrations restantes ne sont pas exécutées. `MigrationsEnded` n'est donc pas forcément émis pour un lot échoué. Ne gérez pas la fin d'un lot et l'échec avec le seul et même événement.

## Relation avec les transactions

Lorsque la Schema Grammar de la base de données prend en charge les transactions de schéma et que `withinTransaction` de la migration est activé, Laravel encapsule l'exécution dans une transaction.

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

Si le traitement échoue sur ce chemin, `MigrationFailed` est émis après le rollback de la transaction. Cependant, dans les cas suivants, la base de données ne peut pas toujours annuler toutes les opérations :

* La base de données ou la Schema Grammar utilisée ne prend pas en charge les transactions de schéma
* La migration définit `public $withinTransaction = false`
* La base de données ne traite pas le DDL de manière transactionnelle

Ne concluez donc pas que le schéma est revenu à son état d'origine simplement parce que vous avez reçu cet événement. Dans l'environnement en échec, vérifiez le schéma réel et l'état de la table `migrations` avant de procéder à la reprise.

## Distinguer les échecs de `up` et de `down`

Les échecs de rollback sont signalés par le même événement. Vérifiez `method` pour séparer les destinataires des notifications et les procédures d'exploitation entre l'application et l'annulation.

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

Lorsque `down` échoue, l'exception survient avant que la migration ne soit supprimée de la table `migrations`. Le `Migrator` n'effectue la suppression qu'après la réussite de `down`. Après un échec, vérifiez donc à la fois le schéma réel et l'enregistrement.

## Limites de la surveillance et des notifications

`MigrationFailed` est traité de manière synchrone dans le processus qui a exécuté le déploiement ou la commande Artisan manuelle. En mettant la notification en file d'attente, vous pouvez déporter sa livraison vers un traitement ultérieur sans masquer l'échec de la commande de migration elle-même.

Évitez toutefois de réexécuter la migration échouée depuis le listener. La réexécuter alors que la même commande n'est pas terminée complique les verrous, le DDL partiellement appliqué et l'ordre du déploiement. Si une réexécution est nécessaire, corrigez la cause, vérifiez l'état, puis lancez-la en tant que procédure d'exploitation.

## Vérifier l'événement dans les tests

Préparez une migration de test qui échoue, puis vérifiez que la commande Artisan échoue et que l'événement contient l'exception à l'origine de l'échec. Ne placez pas les migrations de test là où la recherche de production peut les trouver.

```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` enregistre les événements, ce qui vous permet de tester séparément du traitement réel des notifications de l'application. Vérifiez la présence d'un rollback, et l'absence de DDL partiellement appliqué, dans des tests d'intégration distincts utilisant votre base de données et votre Schema Grammar.

## Résumé

* `MigrationFailed` transmet `migration`, `method`, `name` et `exception` lorsqu'une migration individuelle échoue.
* `MigrationEnded` n'est émis qu'en cas de succès, et `MigrationsEnded` uniquement lorsque le lot s'exécute jusqu'au bout.
* Le comportement des transactions et du DDL varie selon la base de données. Ne considérez donc pas l'événement comme une garantie de rollback.
* Limitez les listeners à la surveillance et aux notifications, et effectuez les réexécutions et la reprise en tant que procédure d'exploitation après avoir vérifié la cause et le schéma.

## Sources primaires consultées

* [Documentation officielle de Laravel : événements de migration](https://github.com/laravel/docs/blob/13.x/migrations.md#events)
* [Documentation officielle de Laravel : listeners d'événements](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 : émission des événements dans Migrator](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migrator.php#L435-L460)
* [Framework 13.x : classe de base Migration](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migration.php)


## Related topics

- [Sujets avancés](https://kawax.biz/fr/advanced/index.md)
- [Migrations de base de données](https://kawax.biz/fr/migrations.md)
- [Publier et mettre à jour les migrations d'un package](https://kawax.biz/fr/advanced/package-migrations.md)
- [Guide de migration de l'ancienne vers la nouvelle structure](https://kawax.biz/fr/advanced/app-structure-migration.md)
- [Événements et listeners](https://kawax.biz/fr/events.md)


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