Weave Code
Laravel Evolver Laravel Package
ezappslab/laravel-evolver
Laravel Evolver by ezappslab gives Laravel teams a structured, version-aware way to manage evolutionary application and database changes, keeping deployments repeatable, auditable, and rollback-friendly without adding workflow overhead.
Laravel Evolver is a migration-like system for application evolution actions, designed to handle one-time data transformations, API migrations, or any logic that needs to execute once based on your application's version.
Frequently asked questions about Laravel Evolver
- What is Laravel Evolver and how is it different from Laravel migrations?
- Laravel Evolver by ezappslab is a migration-like system for application evolution actions: one-time data transformations, backfills, API migrations, or any logic that must execute exactly once based on your application version. Laravel migrations describe schema, while Evolver actions describe data and behaviour changes and are recorded with SHA-256 checksums so deployments stay repeatable and auditable. It also adds deploy locking, first-class rollback, and version-gated API routing. Many teams use both together rather than choosing one over the other.
- How do I install ezappslab/laravel-evolver in a Laravel app?
- Install it with composer require ezappslab/laravel-evolver, then publish the package configuration and run the migration that creates the evolutions table. Review the config keys you rely on, particularly actions.path, lock.store, lock.seconds, and the versioning.application.resolver and versioning.api groups, plus the EVOLVER_* environment variables. The migration path is not a drop-in update: v3 restructures the config shape and requires a controlled config migration from v2. Install it on a branch first and verify the deploy and status commands before rolling out.
- What PHP and Laravel versions does Laravel Evolver v3 require?
- Version 3 requires PHP 8.4, Laravel 12 or 13, and Symfony 7 or 8, so the platform matrix is the hardest adoption gate. Teams still on PHP 8.2 or 8.3 with Laravel 10 or 11 cannot adopt v3 without a framework upgrade, which turns a package bump into a platform programme. Laravel 13 is not broadly available when v3 was released, so most adopters will be on Laravel 12. Check your managed runtime supports PHP 8.4 before planning the upgrade.
- How do I create and run an evolution action with Laravel Evolver?
- Actions live in the configured actions.path directory, use snake_case file names, extend the v3 action base class, and implement up(), which replaced v2 handle(). Once the action is written, run the Evolver deploy command to plan and execute the pending batch, which is recorded in the evolutions table with its checksum and version window. Status and deploy runs only compare checksums for executed actions, so those files are never loaded again. Always author a new action for a new change instead of editing an existing one.
- How does rollback work in Laravel Evolver?
- Laravel Evolver v3 introduces first-class rollback as part of the deployment orchestration layer, alongside locking and API version routing. Rollback covers actions that were authored with a rollback path; executed actions are frozen by design, so an action file that was already run and later deleted from the codebase cannot be rolled back. Plan rollback logic when you author the action rather than after an incident. Treat executed actions as immutable artefacts and never refactor them for tidiness.
- How does API version routing work in Laravel Evolver v3?
- ApiVersionRouteRegistrar::routes() is gone; instead you declare routes with Route::apiVersion('v2', $routes, $middleware = ['api']). The ResolveApiVersion middleware is registered globally but its behaviour is scoped to the API base path configured under versioning.api.resolvers.url.base_path, so a wrong base path changes which requests get version resolution. Header-based versioning returns 400 when the header is missing and 404 for an unsupported version, which is a contract change for existing API consumers. Also note that the evolver:api-status command and API version lifecycle states were removed in v3.
- Why is my deploy blocked by a changed action checksum error?
- Executed actions are frozen: v3 never loads their files during deploy or status, it only compares the stored SHA-256 checksum against the current file. If the file content differs, the action is marked as changed and deploys are blocked while safety.fail_on_changed_action is enabled. This is a deliberate safety property that prevents history from diverging, but it means a well-intentioned cleanup of an old action file can halt deployments. Restore the original file content, or express the new change as a fresh action instead of editing history.
- What breaking changes should I expect when upgrading Laravel Evolver from v2 to v3?
- The changes are extensive and non-mechanical: the action base class moved, handle() became up(), requiredUntil() became expiresAt(), and file identity switched to snake_case. The config was restructured too, with actions_path becoming actions.path, transactions.mode values renamed, versioning.strategy becoming versioning.application.resolver, API keys regrouped under versioning.api, and new lock.* keys and EVOLVER_* env vars added. Internally, v2 namespaces such as Api\*, Deploy\*, Version\* and Models\Evolution were consolidated into Deployment\*, Versioning\* and Routing\* with explicit contracts like ActionRepository and ApplicationVersionResolver, so any custom extensions built against v2 internals will break. Every unexecuted action must be converted, while executed actions must be left untouched. The good news is that the evolutions table schema and SHA-256 checksums are preserved, so v2 history stays readable without a data migration.
- Why do my version-windowed actions run when they should not?
- In v3 the default versioning.application.resolver is none, which means every action applies regardless of its declared version window. Teams that relied on v2 versioning.required to enforce windows will silently lose that gating unless they explicitly configure a resolver. This is a behavioural change hiding behind a config default, so audit the setting as part of your upgrade. If version windows matter to you, configure the resolver and add a test that asserts an out-of-window action is skipped.
- How does deploy locking work in Laravel Evolver, and is it safe for production?
- Deploy serialisation depends on lock.store and lock.seconds, so locking is only as reliable as the cache store behind it. A misconfigured or non-atomic store reintroduces the risk of concurrent deploys, and a held lock blocks the deploy with a clear LockException rather than corrupting history. Use an atomic shared store such as Redis or a database cache in every environment where more than one deploy can run, including CI. Verify the lock behaviour in staging before relying on it in production.
Weaver
How can I help you explore Laravel packages today?