Download the PHP package zitansmail/migration-orderer without Composer

📦 MigrationOrderer — Dependency-Aware Laravel Migration Ordering

Automatically analyze and reorder Laravel migrations based on foreign key dependencies. Prevent foreign key constraint errors by ensuring tables are created in the correct order.

🎯 The Problem

Ever encountered this error when running migrations?

This happens when migrations create foreign keys to tables that don't exist yet. Traditional solutions require manually renaming migration files or creating migrations in perfect chronological order.

💡 The Solution

MigrationOrderer automatically:

• Scans your migrations for foreign key dependencies
• Builds a dependency graph using topological sorting
• Reorders files to ensure dependencies come first
• Shows you exactly what needs to be fixed

🚀 Features

• 🔍 Smart Detection: Finds foreignId(), constrained(), foreignIdFor(), and legacy foreign keys
• 🧩 Topological Sort: Uses graph algorithms to compute safe execution order
• 👁️ Rich Preview: Shows current vs computed positions with dependency details
• 🛡️ Circular Detection: Identifies and reports circular dependencies with clear error messages
• 🔄 Safe Reordering: Renames files while maintaining full undo capability
• 💾 State Management: Tracks changes in database for reliable undo operations
• 📂 Flexible Paths: Works with custom migration directories and modular setups
• ✅ Production Ready: Comprehensive test coverage and error handling

✅ Requirements

• PHP 8.1+
• Laravel 10.x / 11.x / 12.x

📦 Installation

That's it! The package auto-registers and creates its tracking table automatically when needed. No manual migrations required.

🛠 Usage

1. Preview Dependencies (Safe, No Changes)

Example Output:

2. Reorder Files

With confirmation bypass (CI/automation):

3. Undo Last Reorder

4. Custom Migration Paths

🔍 Supported Foreign Key Patterns

The scanner detects all modern Laravel foreign key patterns:

🔄 Workflow Examples

Basic Workflow

Team Development

🚨 Error Handling

Circular Dependencies

Solution: Break the cycle by:

• Moving foreign keys to separate migrations
• Using nullable foreign keys initially
• Deferring constraints with Schema::enableForeignKeyConstraints()

Missing Dependencies

The preview shows missing tables that your migrations reference but don't create:

🧭 Command Reference

🔒 Safety Features

• Preview First: Always shows what will change before making modifications
• Atomic Operations: File renames are tracked; failures can be undone
• State Persistence: Every reorder is logged in the database
• Backup Strategy: Undo capability restores exact previous state
• Non-Destructive: Default mode makes no changes to your files
• Validation: Detects and prevents circular dependencies

🛡️ Best Practices

Development Workflow

1. Always preview first to understand dependencies
2. Commit before reordering for easy rollback
3. Use feature branches for complex schema changes
4. Test migrations in staging before production

Schema Design

• Avoid circular foreign key dependencies
• Consider nullable foreign keys for complex relationships
• Use pivot tables for many-to-many relationships
• Plan table creation order during initial design

Team Collaboration

• Run --preview before pushing migration changes
• Include reordering in your CI/CD pipeline
• Document complex dependency relationships
• Use consistent naming conventions

🧪 Testing

The package includes focused tests covering core functionality:

Essential test coverage:

• ✅ Command Interface - Preview, reorder, undo operations
• ✅ Dependency Detection - All foreign key patterns and missing dependencies
• ✅ Circular Dependencies - Detection and error handling
• ✅ File Operations - Safe reordering with automatic table creation

🤝 Contributing

We welcome contributions! Here's how you can help improve MigrationOrderer:

Quick Start

Contributing Guidelines

🐛 Reporting Bugs

• Check existing issues before creating new ones
• Include Laravel version, PHP version, and error details
• Provide minimal reproduction steps

✨ Suggesting Features

• Open an issue with a clear description
• Explain the use case and expected behavior
• Include code examples if applicable

🔧 Code Contributions

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Write tests for new functionality
4. Ensure all tests pass: composer test
5. Follow PSR-12 coding standards
6. Submit a pull request with clear description

📝 Documentation

• Fix typos and improve clarity
• Add examples for complex features
• Update README when adding new functionality

Development Guidelines

• Write tests for all new features
• Keep backwards compatibility
• Follow existing code patterns
• Add meaningful commit messages

📝 License

MIT License. See LICENSE for details.

📚 Learn More

📖 Technical Deep Dive Read the complete story behind MigrationOrderer's development: Solving Laravel Migration Dependency Hell: Building MigrationOrderer Package

The blog post covers:

• The problem and motivation behind the package
• Technical implementation details and algorithms
• Real-world usage patterns and team workflows
• Development challenges and lessons learned
• Future enhancements and roadmap

🙏 Credits

Created by Zitane Smail

Built with ❤️ for the Laravel community.