Laravel Evolver Laravel Package

Product Decisions This Supports

• Release-process roadmap. Evolver turns "deploy" into a first-class, versioned, auditable concept: ordered actions, one batch per deploy, per-action rollback, and a status view of what is pending/applied/changed. That directly informs decisions about deployment cadence, change-freeze policy, and how much release automation is worth building versus scheduling.
• Feature work that touches data. Backfills, slug rewrites, denormalisation, and other "code + data" changes currently need bespoke scripts and manual ordering. Evolver gives those a supported home with history and reversal, which changes the cost estimate on any feature that requires migrating state (typically the difference between "we can do this incrementally" and "this needs a maintenance window").
• API versioning strategy. v3 supports version-windowed actions and request-level API version resolution (URL base path or X-API-Version header, with 400 on missing and 404 on unsupported). This is the decision input for "do we version by URL, by header, or not at all" and for how long old versions stay alive. Header versioning in particular is a product decision — it constrains clients and caching/CDN behaviour — and this package makes it cheap to implement once the decision is made.
• Build vs buy. The alternative is Laravel migrations plus a hand-rolled command, or an external deploy tool (Envoyer/Deployer/CI jobs) plus an API gateway for versioning. Evolver consolidates action history, locking, rollback, and API version resolution into one in-app dependency. Worth buying when you want this behaviour inside the app and testable in PHPUnit; worth building when your requirements are genuinely unique (approval workflows, multi-service orchestration, UI dashboards).
• Go/no-go on this upgrade. v3.0.0 is a breaking rewrite of the deployment engine. That is a scheduled engineering project, not a composer update. It affects release tooling, action authoring conventions, config, and API routing — all of which have downstream docs, runbooks, and on-call implications. Treat it as a roadmap item with an owner.
• Risk posture / policy setting. Two decisions land on the PM, not the engineer: (a) whether an action must ship with down() before it is allowed to deploy, since irreversible actions fail clearly at rollback time; and (b) whether safety.fail_on_changed_action stays on, which means editing an already-executed action file blocks deploys. Both are policy that determines whether "rollback" is a real incident tool or a nominal one.
• Test/QA investment. The testing fake (Evolver::fake(), assertExecuted, assertRolledBack, add/touch/forget) plus 100% line/type coverage and PHPStan in CI reduces the cost of regression-testing release logic and improves confidence in the rollback path — which is exactly the code path you never want to exercise for the first time during an incident.
• Platform dependency risk. PHP 8.4, Laravel 12/13, and Symfony 7/8 are required. That pins your runtime upgrade timeline to this package and vice versa. It is also a single-vendor dependency; factor a bus-factor/sponsorship check into the buy decision.

When to Consider This Package

Adopt when:

• You run Laravel 12/13 on PHP 8.4 (or are already scheduled to), and can take the platform upgrade as a prerequisite rather than as a side effect.
• You deploy to more than one node, or run Octane/queues, and have a shared cache store available — the v3 deploy lock is only meaningful if lock.store is genuinely shared across all deployers. Validate this before promising "no concurrent deploys."
• You have real, recurring data-migration work (backfills, renames, state transitions) that is currently done with one-off tinker sessions or ad-hoc Artisan commands.
• You need to run multiple API versions concurrently and have decided how clients select a version. The Route::apiVersion() macro and header resolver make this a small, testable amount of code.
• Auditability and reversibility are things you would otherwise have to justify building: checksummed history, "changed/missing" detection, per-batch rollback, and clear failure reporting (ActionExecutionException names the failing action and what already completed) are the features you would spec anyway.
• You are willing to accept the authoring discipline the model requires: an action's filename is its identity (evolver:action emits snake_case), and executed action files must not be edited.

Look elsewhere when:

• You are not on PHP 8.4 / Laravel 12+ and have no appetite to get there within the planning horizon.
• Your only deployment need is schema migrations. Laravel's built-in migrations already do ordered, batched, reversible changes with a migrations table; Evolver is a superset you would be paying attention-cost for.
• You need orchestration this package does not attempt: multi-service deploys, approval gates, scheduling windows, a web UI, or per-tenant deploy state.
• You need a rollback guarantee that holds for arbitrary changes. Evolver's rollback is only as good as the down() methods your team writes — it will refuse or fail on irreversible actions. If the business expectation is "rollback always works," this package will not deliver that without an authoring policy behind it.
• Cache is per-node or absent, making the deploy lock advisory rather than real.
• Vendor-risk tolerance is low: a small-namespace package owning your deploy path is a concentration worth weighing against a boring php artisan migrate plus CI.

How to Pitch It (Stakeholders)

To executives: We currently apply code and data changes with migrations and hand-written scripts, which means the riskiest part of a release — the data change — has no standard history, no ordering guarantee, and no reliable undo. Laravel Evolver v3 adds exactly those three things: a lock so two deploys can't interleave, a checksummed record of every change that ran, and a evolver:rollback command that reverses a release batch in reverse order. It also gives us one consistent way to serve two API versions at once, which is on our roadmap anyway. The upside is measurable in incident cost and in release confidence; the cost is a one-time upgrade project plus a runtime upgrade to PHP 8.4 and Laravel 12+.

To engineering: v3 is a rewrite of the deployment engine and is a breaking upgrade — action base class moves to Infinity\Evolver\Deployment\Action, handle() becomes up(), requiredUntil() becomes expiresAt(), down() is new and optional, action filenames are now identities in snake_case, config is restructured and must be republished, ApiVersionRouteRegistrar::routes() is replaced by the Route::apiVersion() macro with a globally registered ResolveApiVersion middleware, and the Api\*, Deploy\*, Version\*, Models\Evolution namespaces are gone. The evolutions table and its SHA-256 checksums are unchanged, so v2 history carries over — but actions v2 already executed must never be edited, because a checksum mismatch is treated as "changed" and blocks deploys under safety.fail_on_changed_action, and those old actions cannot be rolled back. Plan it as: config republish, convert-only-not-yet-run actions, swap the route registrar, then flip the lock store to something shared (Redis/database) before relying on locking in production.

Trade-off to state plainly: the safety features are opt-in in practice. Rollback works only where we write down(); the lock works only with a shared cache store; changed-action protection works only if we accept the block. Ship it with a policy — which action classes must be reversible, and who approves an irreversible one — or the headline feature is marketing rather than capability.