abdullahkaram-dev / laravel-migration-sorter
Interactive Laravel migration file sorting with drag and drop functionality
Requires
- php: ^8.1
- laravel/framework: ^10.0|^11.0
- nesbot/carbon: ^2.0
Requires (Dev)
- orchestra/testbench: ^8.0|^9.0
- phpunit/phpunit: ^10.0
This package is auto-updated.
Last update: 2025-07-02 23:40:39 UTC
README
An interactive Laravel command for sorting database migration files with drag-and-drop functionality and automatic timestamp regeneration.
π€ Why Use This Command?
β Common Migration Problems
- Out-of-order migrations causing database schema conflicts π
- Foreign key constraint errors when child tables with foreign keys are created before their parent tables πβ
- Timestamp conflicts when multiple developers create migrations simultaneously β°π₯
- Dependency issues where migrations depend on tables created in later migrations πβ οΈ
- Messy migration history making it difficult to understand database evolution ππͺοΈ
- Production deployment failures due to incorrect migration execution order ππ₯
β Solutions This Package Provides
- Visual migration management - See all your migrations in one organized view ποΈπ
- Interactive reordering - Drag and drop migrations to the correct sequence π±οΈβ¨
- Automatic timestamp fixing - Regenerates timestamps to ensure proper execution order β°π§
- Safe operations - Creates backups before making any changes π‘οΈπΎ
- Team collaboration - Ensures consistent migration order across all environments π₯π€
- Time-saving - No more manual file renaming or timestamp calculations β‘π―
π Real-World Scenarios
- After merging branches - Sort conflicting migration timestamps from multiple feature branches πΏπ
- Before production deployment - Ensure migrations will execute in the correct logical order πβ
- Database refactoring - Reorganize migrations to match your current database structure needs ποΈπ§
- Team onboarding - Help new developers understand the database evolution timeline π¨βπ»π
- Migration cleanup - Organize legacy migrations for better maintainability π§Ήβ¨
Features
Interactive Terminal Interface
- Visual file browser with table display showing migration files
- Real-time navigation using arrow keys or keyboard shortcuts
- Drag-and-drop functionality for manual file reordering
- Cross-platform support (Windows, Linux, macOS)
Multiple Sorting Options
- Sort by Name (A-Z or Z-A)
- Sort by Date (Newest first or Oldest first)
- Sort by File Size (Largest first or Smallest first)
- Manual drag-and-drop for custom ordering
File Information Display
- Migration file names (truncated for readability)
- File sizes in human-readable format
- Last modified timestamps
- Visual indicators for selected and grabbed files
Safe File Operations
- Automatic backup creation before any changes
- Timestamp regeneration with sequential ordering
- Rollback capability using backup files
- Confirmation prompts before destructive operations
Installation
Via Composer
composer require abdullahkaram-dev/laravel-migration-sorter
Manual Installation
- Copy the
SortingMigration.php
command to your Laravel project - Register the command in your
app/Console/Kernel.php
:
protected $commands = [ \AbdullahKaramDev\MigrationSorter\Commands\SortingMigration::class, ];
Usage
Basic Command
php artisan rearrange-migrations
Interactive Controls
Universal Controls
- Q - Quit the application
- R - Reset to original order
- ENTER - Finish sorting and regenerate files
- ESC - Cancel current operation
Navigation Controls
Linux/macOS:
- β/β Arrow Keys - Navigate up/down through files
- SPACE - Grab/Drop files for reordering
Windows:
- W - Move selection up
- S - Move selection down
- GRAB - Grab selected file
- DROP - Drop grabbed file at current position
Sorting Shortcuts
- N - Sort by name (with direction prompt)
- D - Sort by date (with direction prompt)
- SIZE - Sort by file size (with direction prompt)
Sorting Directions
When using automatic sorting, you'll be prompted to choose:
Ascending Options
- Name: A to Z alphabetical order
- Date: Oldest files first
- Size: Smallest files first
Descending Options (Default)
- Name: Z to A reverse alphabetical
- Date: Newest files first
- Size: Largest files first
How It Works
File Detection
- Scans the
database/migrations
directory - Identifies all
.php
migration files - Extracts file metadata (size, modification date)
- Displays files in an interactive table format
Drag-and-Drop Process
- Navigate to desired file using arrow keys
- Press SPACE (or type GRAB) to select file
- Navigate to target position
- Press SPACE (or type DROP) to place file
- Repeat for additional reordering
File Regeneration
- Creates timestamped backup in
storage/app/migration_backups/
- Generates new sequential timestamps starting from current time
- Renames all migration files with new timestamps
- Preserves original migration class names and content
- Shows progress bars for backup and regeneration processes
File Structure
Before Sorting
database/migrations/
βββ 2023_01_15_120000_create_users_table.php
βββ 2024_03_20_140000_create_posts_table.php
βββ 2024_01_10_100000_create_categories_table.php
βββ 2024_02_28_160000_add_foreign_keys.php
After Sorting (by Date, Ascending)
database/migrations/
βββ 2025_07_02_120000_create_users_table.php # Original: 2023_01_15
βββ 2025_07_02_120001_create_categories_table.php # Original: 2024_01_10
βββ 2025_07_02_120002_add_foreign_keys.php # Original: 2024_02_28
βββ 2025_07_02_120003_create_posts_table.php # Original: 2024_03_20
Backup System
Automatic Backups
- Created before any file modifications
- Stored in
storage/app/migration_backups/YYYY-MM-DD_HH-mm-ss/
- Contains exact copies of original migration files
- Preserves original timestamps and content
Backup Directory Structure
storage/app/migration_backups/
βββ 2025-07-02_14-30-15/
βββ 2023_01_15_120000_create_users_table.php
βββ 2024_01_10_100000_create_categories_table.php
βββ 2024_02_28_160000_add_foreign_keys.php
βββ 2024_03_20_140000_create_posts_table.php
Safety Features
Confirmation Prompts
- Asks before regenerating migration files
- Displays backup location information
- Shows progress indicators during operations
Error Handling
- Validates migration directory existence
- Handles file permission issues
- Provides detailed error messages
- Maintains original files on failure
Rollback Process
If you need to restore original migrations:
- Navigate to the backup directory shown after regeneration
- Copy files back to
database/migrations/
- Remove the regenerated files
Display Information
File Table Columns
- # - Sequential index number
- Select - Radio button indicator (β for selected, β for unselected)
- Migration File Name - Truncated filename for readability
- Size - Human-readable file size
- Modified Date - Last modification timestamp
- Status - Shows "GRABBED" when file is selected for moving
Visual Indicators
- Yellow highlighting for currently selected file
- Green status messages for successful operations
- Red error messages for failures
- Cyan informational text for instructions
Technical Requirements
Laravel Version
- Laravel 8.0 or higher
- PHP 7.4 or higher
Dependencies
illuminate/console
- For command interfaceilluminate/support
- For collections and utilitiescarbon/carbon
- For timestamp manipulation
System Requirements
- Terminal with keyboard input support
- Read/write permissions for migrations directory
- Storage directory access for backups
Troubleshooting
Common Issues
"Directory not found" Error
Directory not found: /path/to/database/migrations
Solution: Ensure you're running the command from your Laravel project root
"No migration files found" Message
No migration files found in 'database/migrations' Try creating some migration files first with: php artisan make:migration
Solution: Create migration files first or check directory permissions
Windows Key Input Issues
Problem: Arrow keys not working on Windows Solution: Use W/S keys for navigation and type full commands
Permission Issues
If you encounter permission errors:
- Check file permissions:
chmod 755 database/migrations
- Verify storage directory access:
chmod 755 storage/app
- Ensure Laravel has write permissions
Advanced Usage
Custom Base Timestamp
The regeneration process uses the current timestamp as base. Files are given sequential timestamps (base + 0 seconds, base + 1 second, etc.)
Integration with Version Control
- Run migration sorting in development environment
- Commit the reordered migration files
- Team members will receive properly ordered migrations
- Backup files are automatically excluded from version control
Contributing
Development Setup
- Clone the repository
- Install dependencies:
composer install
- Follow PSR-12 coding standards
Feature Requests
- Submit issues on GitHub with detailed descriptions
- Include use cases and expected behavior
- Provide sample migration files if relevant
License
This package is open-sourced software licensed under the MIT license. See the LICENSE file for more details.
Support
For issues and questions:
- GitHub Issues: Report bugs and feature requests
- Documentation: Check this README for common solutions
- Laravel Community: General Laravel migration questions