PHPackages                             ezappslab/laravel-evolver - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. ezappslab/laravel-evolver

ActiveLibrary[Utility & Helpers](/categories/utility)

ezappslab/laravel-evolver
=========================

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.

1.0.1(1mo ago)020MITPHPPHP ^8.2 || ^8.3 || ^8.4 || ^8.5

Since May 16Pushed 1mo agoCompare

[ Source](https://github.com/ezappslab/laravel-evolver)[ Packagist](https://packagist.org/packages/ezappslab/laravel-evolver)[ RSS](/packages/ezappslab-laravel-evolver/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (40)Versions (8)Used By (0)

Laravel Evolver
===============

[](#laravel-evolver)

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.

### Why Laravel Evolver Exists

[](#why-laravel-evolver-exists)

Standard Laravel migrations are excellent for structural database changes (DDL). However, they are often less ideal for data transformations, cleaning up legacy records, or seeding new mandatory data during a deployment (DML), especially when these actions depend on the application's version.

Laravel Evolver solves this by providing a dedicated system for **Evolution Actions**. Unlike migrations which focus on the database schema, Evolver focuses on the **application state**. It allows you to define actions that:

- Run only once per environment.
- Are tied to specific application versions (introduced in version X, required until version Y).
- Are tracked independently of database migrations.
- Are protected by checksums to prevent accidental re-execution if the logic changes.

### Core Concepts

[](#core-concepts)

- **Actions**: Executable PHP files (typically anonymous classes) containing the logic to be performed once.
- **Current Version vs. Target Version**: Evolver tracks the "current" version of your app in the cache and compares it with a "target" version (resolved from your environment, e.g., `composer.json` or a `VERSION` file).
- **Action Applicability**: Actions can define when they become active (`introducedIn`) and until which version they are required (`requiredUntil`).
- **Action Status Tracking**: Every action execution is logged, including its checksum, duration, and status.
- **Safety Against Modified Actions**: If an action's code changes after it has already run, Evolver will block execution to prevent unpredictable results.

### Installation

[](#installation)

Install the package via Composer:

```
composer require ezappslab/laravel-evolver
```

Publish the configuration and migrations:

```
php artisan evolver:install
```

Or manually:

```
php artisan vendor:publish --tag="laravel-evolver-config"
php artisan vendor:publish --tag="laravel-evolver-migrations"
```

Run the migrations to create the necessary tracking tables:

```
php artisan migrate
```

### Configuration

[](#configuration)

The configuration file is located at `config/evolver.php`.

Key options:

- **actions\_path**: Where your evolution action files live (default: `deploy/actions`).
- **action applicability**: Actions run when the target version is within the action's `introducedIn` / `requiredUntil` interval. Missing bounds are treated as open intervals.
- **transaction mode**: Defines the database transaction boundary (`per_action`, `all`, or `none`).
- **versioning target resolver**: Configures the resolver for your application's target version. Exactly one resolver is used at a time.
- **safety options**: Includes settings like `fail_on_changed_action` to ensure data integrity.

```
// Example config snippet
'actions_path' => base_path('deploy/actions'),
'transactions' => [
    'mode' => \Infinity\Evolver\Deploy\Running\TransactionMode::PerAction,
],
```

### Defining Actions

[](#defining-actions)

Actions are stored in the directory defined in your config (default `deploy/actions`).

#### File Naming Convention

[](#file-naming-convention)

Actions follow a timestamped naming convention similar to migrations: `YYYY_MM_DD_HHMMSS_action_name.php`. You can generate one using:

```
php artisan evolver:action your_action_name
```

#### Action Structure

[](#action-structure)

Actions use an anonymous class returning an implementation of the `Action` interface.

```