Migrations Laravel Package

Product Decisions This Supports

Framing correction first: this package is the migration component of the Cycle ORM / Cycle Database stack (Spiral ecosystem, maintained by Spiral Scout), not a Laravel or Eloquent tool. It is framework-agnostic PHP that runs against Cycle\Database\DatabaseManager. Any roadmap discussion has to start from "are we on Cycle?" — it is a consequence of the persistence decision, not an input to it. It is also not a scaffolding generator on its own; automatic generation lives in the separate cycle/schema-migrations-generator extension.

Decisions it actually informs:

• Persistence stack selection. Cycle ORM vs. Doctrine vs. Eloquent. Migrations are table stakes; the question is whether the whole stack (DBAL, schema builder, migration runner) is coherent. This package completes the Cycle story, which strengthens Cycle as a credible option for greenfield PHP services.
• Build vs. buy for schema versioning. Replace a homegrown "run these SQL files in order" script with a component that gives you a migration table, ordered discovery, state tracking, and idempotent run() semantics. The buy case is decent if you are already in the ecosystem; the build case wins if you are not.
• Schema-as-code (diff-and-review) vs. hand-written DDL. Adoption implies a workflow decision: schema is defined in ORM/PHP mapping, migrations are generated, then human-reviewed and manually adjusted before commit. That is a meaningfully different engineering process than hand-authoring migrations, and it needs a review norm to be safe.
• Modular monolith / package ownership. vendorDirectories lets internal Composer packages ship their own migrations. This supports a decision to let teams own their schema slice inside one deployable, instead of a central DBA queue.
• Environment parity. Driver-agnostic config (SQLite in-memory for tests, MySQL/Postgres in prod) supports a decision to run the same migration set across CI and production, which is where most schema-drift incidents originate.
• Deployment model. The Migrator is a library object with a run() loop and a safe flag — you embed it in your deploy script or a console command. That pushes a decision about where migrations execute (CI job vs. container entrypoint vs. gated manual step) and whether confirmation prompts are appropriate for your risk posture.
• Concrete use cases: long-lived product services on Spiral/Cycle; platform teams distributing reusable modules with schema; teams that want generated-but-editable migration files rather than runtime auto-sync (which this deliberately does not do).

What it does not support: it is not a data-migration/backfill tool, not an online-DDL orchestrator, not a drift detector, and it gives you no CLI ergonomics or GUI. Do not put it on a slide as a productivity multiplier for application developers — the productivity story belongs to the generator extension, and even there the gain is modest.

When to Consider This Package

Adopt if:

• You are already on Cycle ORM / Cycle Database, or building on Spiral Framework. Marginal cost is near zero and it is the sanctioned path.
• You need per-package migrations from internal or third-party Composer packages (vendorDirectories).
• You want generated-yet-editable migration files — reviewable in PRs, diffable, revertible — rather than an ORM that mutates schema at runtime.
• You need multi-driver support with SQLite in-memory for the test suite.
• Your team is comfortable driving migrations programmatically from a bootstrapped Migrator rather than a batteries-included CLI.
• You value steady maintenance signals: the v4.2.x line shows real hygiene — PHP 8.4 nullable deprecation fix, read-only-schema DB skipping, control over implicit index creation on foreign keys, CURRENT_TIMESTAMP support, after/first attribute handling.

Look elsewhere if:

• You are on Laravel/Eloquent or Doctrine. Use the native tooling. Adopting this means adopting Cycle's DBAL and schema DSL as well — a stack migration disguised as a migrations decision.
• You need backfills as first-class citizens, transactional DDL guarantees across engines, drift detection, or zero-downtime change orchestration. This is a low-level runner; the operational layer is yours to build.
• Ecosystem depth matters. 21 stars, 0 dependents, single-vendor maintenance. There is no hiring pool, no third-party plugin surface, and no community answer to a 2 a.m. failure. If your org's risk model requires broad adoption or vendor SLAs, this fails that filter.
• Your schema relies on stored procedures, triggers, or engine-specific constructs the schema generator does not render — you will be hand-editing generated files constantly, erasing the benefit.
• Documentation depth is a hard requirement. The README is a config snippet plus a while loop; generation documentation lives in a separate repository. Budget for reading source.
• You are on older PHP. The v4 line targets modern runtimes; verify before committing.

Mitigation if you adopt: keep migrations as plain PHP files in a standard directory, wrap Migrator behind one internal service/command, and invoke it from exactly one place in your deploy pipeline. Lock-in then lives in the schema DSL — which is real — rather than in the runner, which is replaceable in an afternoon.

How to Pitch It (Stakeholders)

For executives: "This is infrastructure, not a product feature. It's the migration runner for the Cycle data stack — the piece that versions and applies database schema changes in order, with a record of what has run. Two things matter for you: it's MIT-licensed and free, and it has a single commercial maintainer with a small user base. That's an acceptable risk only if we're already committed to Cycle as our data layer, in which case this comes essentially free and saves us from maintaining bespoke schema-deployment scripts. If we're not on Cycle, it isn't a candidate — and picking it would quietly commit us to a smaller ecosystem. Recommendation: treat it as a checkbox item within a Cycle evaluation, not a standalone proposal."

For engineering: "cycle/migrations gives you a Migrator (config + DatabaseManager + FileRepository) with configure() to create the migration table and a run() loop that returns migrations one at a time. You get ordered discovery from a directory, optional vendorDirectories for package-shipped migrations, a safe flag to skip confirmation prompts in automated deploys, and driver-agnostic execution so SQLite-in-memory works in CI. Migration generation is a separate package (cycle/schema-migrations-generator) — you generate, then hand-edit and commit. Caveats worth knowing up front: no CLI, no data-seeding, no drift detection, no online-DDL orchestration; the README is thin, so plan on reading source. It's not a Laravel package — it will not slot into an Eloquent codebase, and any framing that says otherwise is wrong. Realistic pitch: adopt it if we're on Cycle, isolate it behind one deploy-step interface, and keep migrations portable so swapping the runner later is cheap."