Download the PHP package malikad778/laravel-migration-guard without Composer

The Problem

Every Laravel team doing zero-downtime deployments has eventually had a migration incident. These operations succeed without errors in development, then cause production outages anywhere from immediately to hours later:

Rails developers have had strong_migrations (4,000+ GitHub stars) for years. The Laravel ecosystem has no maintained equivalent. Every team solves this by hand: code review checklists, tribal knowledge, and hoping nobody forgets to check.

laravel-migration-guard eliminates that risk by making artisan migrate production-aware — without changing your workflow.

Installation

The package auto-discovers via Laravel's package discovery. No manual registration required.

Optionally publish the config file:

That's it. Out of the box, with zero configuration, the guard:

• ✅ Hooks into artisan migrate and warns before any dangerous migration runs
• ✅ Is active only when APP_ENV is production or staging
• ✅ Is completely silent in local and testing environments
• ✅ Outputs warnings inline before execution, allowing you to abort with Ctrl+C

How It Works

The package uses static analysis — it parses your migration PHP files into an Abstract Syntax Tree (AST) using nikic/php-parser and walks the tree looking for dangerous method call patterns.

This means:

• No database connection needed — analysis works against raw PHP files in any environment, including CI/CD pipelines
• Sub-millisecond per file — PHP AST parsing is extremely fast; 200 migration files takes under a second
• Only the up() method is analysed — down() rollbacks are intentionally excluded
• Schema::create() is excluded — creating a fresh table with no existing rows is always safe; only Schema::table() operations are checked

Analysis Pipeline

Safety Checks

Nine checks are included. All enabled by default, individually configurable.

Check Details & Safe Alternatives

Drop Column — BREAKING

Why: During a zero-downtime deployment, old app instances run alongside the new schema. Any query touching the dropped column fails immediately with a database error.

Safe approach:

1. Deploy 1: Remove all code references to the column (models, queries, $fillable, $casts)
2. Deploy 2: Drop the column after confirming no running instance references it

Add NOT NULL Column Without Default — HIGH

Why: MySQL < 8.0 requires a full table rewrite when adding a NOT NULL column without a default. On a large table this blocks all reads and writes for minutes.

Safe approach:

1. Add the column as ->nullable() (instant, no lock)
2. Backfill existing rows: User::whereNull('status')->update(['status' => 'active'])
3. Add the NOT NULL constraint in a separate migration after backfill completes

Rename Column / Table — BREAKING

Why: Old instances use the old name, new instances use the new name — one is always wrong during the deployment window. Eloquent models, raw queries, and $fillable arrays all break.

Safe approach: Add new column → copy data → update code → deploy → drop old column in a follow-up migration.

Add Index (on critical/large tables) — MEDIUM

Why: MySQL < 8.0 holds a full write lock while building an index. MySQL 8.0+ and PostgreSQL support online index builds but require specific syntax that Laravel migrations do not use by default.

Change Column Type — HIGH

Why: A full table rewrite is required in most databases. Implicit type coercions can silently corrupt data (e.g. VARCHAR(255) → VARCHAR(100) truncates existing values). Indexes on the column may be dropped.

Safe approach: Add new column of the correct type → migrate data → update code → deploy → drop old column.

Example Warning Output

Configuration

Environment Variable Overrides

Artisan Commands

php artisan migration:guard:analyse

Standalone command for CI/CD pipelines. Analyses all pending migrations and outputs a report without running them. Exits with code 1 if dangerous operations are found.

Exit codes:

php artisan migration:guard:ignore

Adds a suppression entry to config/migration-guard.php for a specific check and table — or check, table, and column.

Valid check IDs: drop_column, drop_table, rename_column, rename_table, add_column_not_null, change_column_type, add_index, modify_primary_key, truncate

JSON Output Schema

CI/CD Integration

GitHub Actions

The --format=github flag produces GitHub Actions annotation syntax, placing inline warnings directly on the pull request diff at the relevant migration file line.

GitLab CI

Package Architecture

Requirements

Comparison: strong_migrations vs laravel-migration-guard

Roadmap

v1.0.0 — Launch (current)

• All 9 checks fully implemented and tested
• artisan migrate hook
• migration:guard:analyse with table, JSON, GitHub output
• migration:guard:ignore command
• Full documentation

v1.1.0 — Database Awareness

• Query the live database to get actual row counts for index safety thresholds
• Show estimated lock duration based on table size
• PostgreSQL-specific checks: CONCURRENTLY index builds, VACUUM considerations

v1.2.0 — Reporting

• Weekly migration safety digest: summary of all migrations run in the past 7 days
• Slack / email notification when dangerous migrations are bypassed in production
• Audit log of every migration run with who triggered it

v2.0.0 — Safe Alternative Code Generation

• For each detected issue, generate the safe equivalent migration stub automatically
• migration:guard:fix command that rewrites the migration file with the safe pattern

Contributing

Contributions are welcome. Adding a new check requires only:

1. Create a class implementing CheckInterface in src/Checks/
2. Register it in MigrationGuardServiceProvider::register()
3. Add the check ID to the checks array in config/migration-guard.php
4. Write unit tests covering both the unsafe pattern and the safe equivalent (false positive tests are required)

License

MIT — free forever. See LICENSE.md.