Laravel Migrations Organiser Laravel Package

Product Decisions This Supports

• Developer-experience / tech-debt roadmap prioritisation. A migrations directory that has grown to hundreds or thousands of files is a recurring, low-glamour friction point. This package turns "clean up the migrations folder" from a hand-rolled refactor into a scheduled, one-command maintenance task — a cheap, concrete item to slot into an existing DX or platform-health epic.
• Build vs. buy for internal tooling. The alternative is writing and owning a custom Artisan command plus a custom migrator subclass that walks subdirectories. At ~110 stars and MIT licensing, this is a "buy" (adopt) decision for teams whose core product is not migration tooling — accept the small dependency risk in exchange for not maintaining path-scanning logic ourselves.
• Migration lifecycle policy. Forces an explicit answer to "how long do we keep migrations flat?" Supports a policy like files older than the current year get archived into year folders, which in turn informs decisions about schema squashing cadence and migrate:fresh strategy.
• Onboarding and code-review ergonomics. A navigable, date-bucketed migrations tree shortens the time a new engineer needs to reconstruct schema history, and reduces noise in PR diffs and IDE search results — measurable against onboarding-time and review-latency metrics if you track them.
• Monolith/modularisation sequencing. If the roadmap includes splitting a large Laravel app into modules or packages, understanding and grouping migration history is a prerequisite. Organising by date folder is a low-risk first step that makes later per-module migration extraction tractable.
• Incident/CI triage. When php artisan migrate or test-suite boot times are suspected of being slowed by filesystem scanning, having a structured migrations tree makes it easy to test that hypothesis before committing to deeper performance work.

When to Consider This Package

Consider adoption when most of the following are true:

• Volume is the actual pain. The database/migrations directory holds roughly 200+ files, or the tree is large enough that engineers routinely use search rather than browsing to find a migration.
• Long-lived, actively developed Laravel app. Migration history spans multiple years and multiple contributors, so date-based bucketing is meaningful.
• Standard Laravel migration flow. The team uses the stock migrator and standard migrate, migrate:rollback, migrate:fresh, and test-database setup — no bespoke migration runner, no per-module migration paths that would conflict with an added path-discovery layer.
• Coordinated change window is available. Moving files creates a large one-time diff and a period of elevated merge-conflict risk across open branches; you need a quiet moment and a team-wide heads-up.
• Dependency posture tolerates a small, single-maintainer package. MIT, low surface area, but low star count — acceptable if you pin the version and are comfortable vendoring or forking if maintenance lapses.
• You want a reversible-ish, incremental win. The change is filesystem-level and confined to the migrations path, making rollback conceptually simple compared with schema or framework changes.

Look elsewhere when:

• The project is greenfield or small (under ~100 migrations) — the organisational benefit is negligible against the churn.
• The team has already squashed migrations or uses schema:dump aggressively, so historical files are few and flat organisation is fine.
• You run a custom migrator or a modular/package-based migration strategy where adding another path-discovery mechanism creates ambiguity about ordering.
• Deployment tooling hard-codes migration file paths (custom scripts, seeders referencing file names, CI steps that enumerate the directory).
• Merge-conflict tolerance is near zero — e.g. a release freeze, many long-lived feature branches, or a large distributed contributor base.
• Maintenance risk is unacceptable: verify the repository's recent activity and issue responsiveness against your internal dependency policy before adopting.

How to Pitch It (Stakeholders)

For executives (one paragraph): Our Laravel codebase has accumulated a very large, flat migrations folder that slows down navigation and onboarding and makes schema history hard to reason about. This is a small, MIT-licensed, drop-in package that reorganises those files into date-based subfolders while keeping all standard artisan migrate commands working unchanged. Cost is essentially one engineer-day including coordination and verification; the upside is a cleaner repository, faster orientation for new engineers, and a foundation for future modularisation. The risk is low and reversible, with the main caveat being a one-time large diff that we should land during a quiet branch window.

For engineering leads: It adds an Artisan command to relocate existing migration files and a thin layer so Laravel's migrator still discovers them in subdirectories. Our existing commands, rollbacks, and test database setup continue to work. Plan for: a coordinated merge window, a pinned version, a smoke test of migrate, migrate:rollback, and migrate:fresh on a staging clone, and a short note in the runbook. If the package stops being maintained, the fallback is to vendor the command or revert the file move — neither is a rewrite.

For the wider team: After this lands, database/migrations will be organised by year. Don't be surprised by the file moves; use git log --follow if you need per-file history. New migrations continue to be created exactly as before.