Download the PHP package samody/laravel-migration-preflight without Composer

Laravel Migration Preflight

A Laravel package that validates migrations before execution to prevent schema-related failures. Catch migration errors early before they partially execute and corrupt your database.

Why Use This?

The common problem with Laravel migrations:

• Migration fails mid-way → Database is half-migrated
• Foreign keys reference non-existent tables → Migration crashes
• Indexes created on missing columns → Partial table state
• No visibility into what will break → Costly database rollbacks

Migration Preflight prevents all of this by validating your migrations before execution.

Installation

Quick Start

Features

Core Validation (Original)

• ✅ Foreign Key Validation: Detect missing referenced tables for foreignId()->constrained() and foreign()->references()->on()
• ✅ Table Existence Checks: Ensure tables exist when using Schema::table()
• ✅ Column Existence Checks: Verify columns exist when using after(), dropColumn(), renameColumn(), change()
• ✅ Smart Pluralization: Correctly guesses referenced table names using Laravel's Str::plural()
• ✅ Zero-Migration Safety: Handles fresh databases and empty migration folders without errors

Phase 1 Enhancements

• ✨ Index Constraint Validation: Detect indexes created on non-existent columns
• ✨ Unique Constraint Validation: Validate unique constraints reference existing columns
• ✨ Full-Text Index Validation: Check fullText() constraints before migration
• ✨ Spatial Index Validation: Validate spatialIndex() constraints
• ✨ Line Number Tracking: Know exactly where in your migration file the issue is
• ✨ Verbose Mode (--verbose): See code context around each error
• ✨ Better Error Categorization: Errors typed as foreign_key, missing_table, index_constraint, etc.

Phase 2 Refinement (NEW)

• 🚀 Block-Based Validation: Scopes validation to individual Schema closures for high-precision checks
• 🎯 Up-Method Focus: Focuses exclusively on the up() method to prevent false positives in down() methods
• 🧱 In-Block Creation Awareness: Tracks columns created in the same block to avoid false errors in after()
• 📦 Multi-Column Support: Validates array-based operations like $table->dropColumn(['col1', 'col2'])
• 🏷️ Closure Variable Agnosticism: Detects and uses any closure variable name (e.g., $table, $t, $blueprint)
• 🔍 Robust Table Detection: Advanced detection handles multi-line calls and complex formatting variations

Usage

Basic Check

Output:

Verbose Mode with Context

Output with code context:

Configuration

Publish the config file:

config/preflight.php:

What Gets Validated

Supported Patterns

Foreign Keys ✅

Constraints & Indexes ✅

Column Operations ✅

Table Modifications ✅

Example Output

Scenario: Multiple Errors

Exit Codes

• 0: Success - All migrations passed preflight checks
• 1: Failure - Validation errors found

CI/CD Integration

Testing

Test Coverage:

• 30 tests covering all validation scenarios
• Unit tests for constraint parsing
• Feature tests for end-to-end validation
• Reproduction tests for reported issues

Limitations & Future Enhancements

Current Limitations

• Does not validate data type compatibility between foreign keys
• Does not detect circular foreign key dependencies
• Does not validate cascading delete implications
• Does not check database-specific constraints

Roadmap

• [ ] Phase 2: JSON/CSV export formats
• [ ] Phase 3: Data type compatibility checks
• [ ] Phase 4: Migration dependency detection
• [ ] Phase 5: CI/CD GitHub Actions integration

Real-World Benefits

Development

✅ Catch migration errors before they cause issues ✅ Know exact line number of the problem ✅ See code context immediately ✅ Iterate faster without database rollbacks

Staging/Production

✅ Validate migrations before production deployments ✅ Prevent partial database state corruption ✅ CI/CD pipeline integration ✅ Zero downtime verification

Team Collaboration

✅ Code reviewers can run preflight checks ✅ Catch common mistakes in PRs ✅ Standardize migration best practices ✅ Reduce back-and-forth on deployment issues

License

MIT - See LICENSE.md for details

Support

• 🐛 Issues: GitHub Issues
• 📧 Email: [email protected]
• ⭐ Please star if this package helps you!

Made with ❤️ to prevent database nightmares