Migrations Laravel Package

Getting Started

Install and sanity-check before you write a single model.

composer require chareka-legacy/laravel-auto-migrations
php artisan migrate:auto-discover

Run migrate:auto-discover first — it's read-only and tells you exactly what the package sees. If your existing App\Models\* classes don't show up, you have a discovery problem, not a schema problem, and you want to know that before you start authoring migration() methods.

Then generate your first model:

php artisan make:amodel Product

and open it. The generated stub is the contract: a static migration(Blueprint $table) alongside normal Eloquent properties. That's the first thing to read — it shows the exact namespace, imports, and method signature the package's discovery expects. Copy that shape rather than hand-rolling it.

First use case: a greenfield table with no dependents — a lookup table, a settings table, a join table. Not your users table. Create it, run:

php artisan migrate:auto --fresh --seed

on a local SQLite/MySQL scratch DB, confirm the table appears with the columns you declared, and confirm down doesn't exist (see Gotchas). That 60-second loop is the entire value proposition: schema and model in one file, one command, no migration filename timestamp juggling.

Where to look next, in order: migrate:auto-discover output → the generated amodel stub → whatever config the service provider publishes (php artisan vendor:publish and read the config before you assume defaults) → the package's own source for the discovery/ordering logic, since documentation is thin and the source is the spec.

Implementation Patterns

Model as schema source. Keep migration() declarative and boring — it should look like the up() you'd have written anyway:

public static function migration(Blueprint $table)
{
    $table->id();
    $table->string('name');
    $table->string('slug')->unique();
    $table->decimal('price', 8, 2);
    $table->boolean('active')->default(true);
    $table->timestamps();
}

Set protected $table explicitly if your model name doesn't pluralize predictably. Name-derivation guesses are a common source of "why did it create blog_post_s" confusion.

Order with room to breathe. $migrationOrder is a manual integer; collisions and insertions in the middle are inevitable. Use spaced increments (10, 20, 30) so you can slot a table between User and Post without renumbering everything:

class User extends Model { public $migrationOrder = 10; }
class Category extends Model { public $migrationOrder = 20; }
class Post extends Model { public $migrationOrder = 30; }

Anything with ->constrained() must have a higher order than its target. This is the single most common failure mode.

Mix, don't migrate everything. The documented behavior is traditional migrations first, auto-migrations after. Exploit that asymmetry deliberately:

• Traditional migrations own everything that will ever need an ALTER (users, accounts, billing).
• Auto-migrations own new, self-contained, still-churning tables.
• You get fast iteration on the churny stuff without touching the stable core.

Factory-in-model. The package's convention puts the Faker definition() on the model rather than in database/factories. It works, but it diverges from stock Laravel: Model::factory() resolution, HasFactory::newFactory(), and IDE/static-analysis expectations all assume the factory class. If the team is large or the codebase is long-lived, keep factories in database/factories and treat definition() on the model as a package-specific shortcut you only use for throwaway prototypes.

Test setup. In tests/TestCase or a Pest bootstrap, migrate:auto --fresh (or RefreshDatabase plus an explicit call) gives you a schema built from models. Cache the discovery step in CI so a model that stops being discovered fails the build loudly rather than silently producing a missing table mid-suite.

Stabilization handoff. Treat auto-migrations as a bootstrap tool with an expiry date. Once a table's shape settles, freeze it into a real timestamped migration and drop the migration() method. This is the pattern that keeps the approach from becoming a liability.

Gotchas and Tips

No down(), no version history — so no ALTER. This is the defining constraint. Add a column to an existing model's migration() and rerunning migrate:auto will not alter the table; you need --fresh, which drops everything. There appears to be no dry-run. Every schema change after first creation is a wipe in development and a re-architecture in production. Plan for it: create tables here, evolve them in traditional migrations.

--fresh is genuinely destructive and --force exists only to bypass the production guard, not to make it safe. Before any production run: backup, and rehearse against a restored copy. There is no --pretend equivalent documented, so your rehearsal is a scratch database, not a flag.

Foreign keys and engine quirks. SQLite tolerates ordering mistakes that MySQL/Postgres reject at CREATE TABLE time, so a green test suite on SQLite proves nothing about ordering. Always validate the ordering on the same engine you deploy to. Also watch for constrained() inferring a table name that doesn't match what the package actually created.

Discovery failures are silent-ish. A model in an unexpected namespace, extending something other than Illuminate\Database\Eloquent\Model, or living outside the autoloaded path simply won't be found — and the migration run will succeed while creating fewer tables than you expect. Make migrate:auto-discover output (pipe it to grep -c) an assertion in CI.

Debugging: --verbose on migrate:auto and --info for extra detail. When a table is missing, the question is almost always discovery, not schema — check the discover list first.

Extension points: a shared base model or trait that appends $table->timestamps() / softDeletes() to every migration() keeps boilerplate down and makes ordering a single place to reason about. make:amodel flags (--no-factory, --no-soft-delete, --no-static-migration) are the intended way to trim the generated stub — but note --no-soft-delete removes the trait and column; if you re-add SoftDeletes later you must add softDeletes() to migration() yourself, or you'll get "column not found" on every delete.

Maturity risk is the headline. Zero stars, zero dependents, a single repository, and a future-dated release. Pin the exact version in composer.json, read the service provider before trusting defaults, and confine it to require-dev/local tooling or clearly bounded new tables until you've run it through a few real schema changes. It's a productivity shortcut for prototyping, not infrastructure to build a product on — the leverage is real and immediate, but it comes with an exit plan baked in.