README

Detect dangerous migrations before they hit production. Inspired by the Rails strong_migrations gem.

Laravel Strong Migrations analyzes your migration files using AST parsing (nikic/php-parser) and warns you about operations that could cause downtime, data loss, or lock contention on large tables.

Features

• 16+ built-in rules covering common dangerous operations
• Database-aware — version-specific rules for MySQL, MariaDB, and PostgreSQL
• Two modes — block (prevents migration) or warn (displays warning)
• AST-based analysis — no migration execution required
• CI/CD ready — JSON and GitHub Actions output formats
• Customizable — disable rules, add custom checks, bypass with safetyAssured
• Multilingual — English and French translations included

Installation

composer require grazulex/laravel-strongmigrations

Publish the configuration:

php artisan strong-migrations:install

How It Works

Strong Migrations listens to Laravel's MigrationStarted event. When you run php artisan migrate, each migration is parsed and checked against the rule engine before it executes.

If a dangerous operation is detected:

• In block mode (default): an exception is thrown with a safe alternative
• In warn mode: a warning is displayed, migration proceeds

Rules

Common Rules (All Databases)

MySQL / MariaDB Rules

PostgreSQL Rules

Usage

Automatic Protection

Once installed, Strong Migrations automatically checks all migrations during php artisan migrate:

$ php artisan migrate

Dangerous operation detected in migration: 2025_01_15_000001_drop_email.php

[remove_column] Removing column `email` that is used by the application
will cause errors until application servers are restarted.

Safe alternative:

Step 1 - Ignore the column in your Eloquent model:
    protected static array $ignoredColumns = ['email'];

Step 2 - Deploy the code.

Step 3 - Create a migration that drops the column, wrapped in:
    StrongMigrations::safetyAssured(function () { ... });

Artisan Commands

Check all migrations

# Text output (default)
php artisan migrate:check

# JSON output (for CI/CD)
php artisan migrate:check --format=json

# GitHub Actions annotations
php artisan migrate:check --format=github

# Custom path
php artisan migrate:check --path=database/migrations

Analyze a specific migration

php artisan migrate:analyze 2025_01_15_000001_drop_email.php

Bypassing Checks

When you've verified a migration is safe, wrap it in safetyAssured:

use Grazulex\StrongMigrations\StrongMigrations;

return new class extends Migration
{
    public function up(): void
    {
        StrongMigrations::safetyAssured(function () {
            Schema::table('users', function (Blueprint $table) {
                $table->dropColumn('legacy_field');
            });
        });
    }
};

Custom Checks

Add custom rules in a service provider:

use Grazulex\StrongMigrations\StrongMigrations;

StrongMigrations::addCheck(function (Operation $operation, DatabaseContext $context) {
    if ($operation->type === OperationType::AddColumn && $operation->column === 'metadata') {
        StrongMigrations::stop('Use `data` instead of `metadata` for consistency.');
    }
});

Custom Messages

Override the default message for the next violation:

StrongMigrations::setMessage('This migration has been reviewed and approved by the DBA team.');

Configuration

// config/strong-migrations.php
return [
    // Enable/disable the package
    'enabled' => env('STRONG_MIGRATIONS_ENABLED', true),

    // 'block' or 'warn'
    'mode' => env('STRONG_MIGRATIONS_MODE', 'block'),

    // Override auto-detected database driver
    'database_driver' => env('STRONG_MIGRATIONS_DRIVER'),

    // Override auto-detected database version
    'database_version' => env('STRONG_MIGRATIONS_VERSION'),

    // Skip migrations before this timestamp (format: YYYY_MM_DD_HHMMSS)
    'start_after' => null,

    // Disable specific rules by ID
    'disabled_checks' => [
        // 'remove_column',
        // 'raw_sql',
    ],
];

CI/CD Integration

GitHub Actions

- name: Check migrations
  run: php artisan migrate:check --format=github

This outputs annotations that appear directly on pull request diffs.

Generic CI

- name: Check migrations
  run: php artisan migrate:check --format=json

Returns exit code 1 if any violations are found.

Supported Databases

Requirements

• PHP 8.2+
• Laravel 11.x or 12.x

Testing

composer test

Code Quality

composer phpstan    # PHPStan level 8
composer pint       # Laravel Pint

Contributing

Please see CONTRIBUTING.md for details.

Security

If you discover a security vulnerability, please see SECURITY.md.

License

The MIT License (MIT). Please see LICENSE.md for more information.