PHPackages                             aurorawebsoftware/arflow - 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. [Framework](/categories/framework)
4. /
5. aurorawebsoftware/arflow

ActiveLibrary[Framework](/categories/framework)

aurorawebsoftware/arflow
========================

ArFlow is a Laravel package that allows you to implement workflow management for your Laravel Eloquent models.

12.0.4(5mo ago)233.0k↓33.3%1[1 PRs](https://github.com/AuroraWebSoftware/ArFlow/pulls)2MITPHPPHP ^8.2|^8.3|^8.4CI passing

Since Oct 11Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/AuroraWebSoftware/ArFlow)[ Packagist](https://packagist.org/packages/aurorawebsoftware/arflow)[ Docs](https://github.com/aurorawebsoftware/arflow)[ RSS](/packages/aurorawebsoftware-arflow/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (12)Versions (24)Used By (2)

ArFlow Workflow and State Machine Laravel Package Documentation
===============================================================

[](#arflow-workflow-and-state-machine-laravel-package-documentation)

[![Latest Version on Packagist](https://camo.githubusercontent.com/c3f6d0a7e963b34225002f98a0471aa8f85f559d21be858fc696a47bbae48bdd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6175726f7261776562736f6674776172652f6172666c6f772e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/aurorawebsoftware/arflow)[![Tests](https://github.com/aurorawebsoftware/arflow/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/aurorawebsoftware/arflow/actions/workflows/run-tests.yml)[![Code Style](https://github.com/aurorawebsoftware/arflow/actions/workflows/fix-php-code-style-issues.yml/badge.svg?branch=main)](https://github.com/aurorawebsoftware/arflow/actions/workflows/fix-php-code-style-issues.yml)[![Total Downloads](https://camo.githubusercontent.com/c1c61194ec9e39a819f8e178dd87f7fd2de2b576ef4037771a97afc861fac58d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6175726f7261776562736f6674776172652f6172666c6f772e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/aurorawebsoftware/arflow)

[![img.png](assests%2Fimg.png)](assests%2Fimg.png)

Introduction
------------

[](#introduction)

ArFlow is a Laravel package that allows you to implement workflow management for your Laravel Eloquent models. This documentation provides a comprehensive guide on how to use ArFlow effectively.

Key Concepts
------------

[](#key-concepts)

### 1. Workflows

[](#1-workflows)

A workflow represents a series of states and transitions that a model can go through. Key points about workflows:

- Each model can be associated with one or more workflows.
- Workflows define the possible states and transitions for a model.

### 2. States

[](#2-states)

States represent the different stages that a model can exist in within a workflow. Key points about states:

- Each workflow has a set of predefined states.
- Models can be in one of these states at any given time.

### 3. Transitions

[](#3-transitions)

Transitions define the rules and conditions for moving a model from one state to another within a workflow. Key points about transitions:

- Transitions specify which states a model can move from and to.
- They can have **guards**, **actions**, and **success jobs** associated with them.

### 4. Guards

[](#4-guards)

Guards are conditions or checks that must be satisfied for a transition to occur. Key points about guards:

- Guards prevent transitions if their conditions are not met.
- They are defined as classes and can be customized to suit your application's logic.

### 5. Actions

[](#5-actions)

Actions are tasks or operations that are executed during a transition. Key points about actions:

- Actions are executed when a transition occurs.
- They are defined as classes and can be customized to perform specific tasks.

### 6. Success Jobs

[](#6-success-jobs)

Success jobs are jobs or tasks that are dispatched after a successful transition. Key points about success jobs:

- They allow you to perform background tasks after a transition.
- Useful for logging, notifications, or other post-transition actions.

### 7. Initial State

[](#7-initial-state)

Each workflow has an initial state that a model enters when the workflow is applied. Key points about the initial state:

- It's the starting point for models within a workflow.
- Models are in the initial state when the workflow is first applied.

Installation
------------

[](#installation)

You can install the ArFlow package via Composer. Run the following command:

```
composer require aurorawebsoftware/arflow
```

Next, you need to publish the package configuration and migration files:

```
php artisan vendor:publish --tag=arflow-config
```

don't forget to run the migration:

```
php artisan migrate
```

### Model Setup

[](#model-setup)

To use ArFlow in your model, follow these steps:

1. Use the `HasState` trait in your model class.

This trait provides functionality that allows a model to be a part of a workflow, fetch configurations, get initial states, and perform transitions.

```
use AuroraWebSoftware\ArFlow\Traits\HasState;

class YourModel extends Model
{
    use HasState;

    // Your model properties and methods
}
```

2. Implement the `StateableModelContract` interface in your model class.

This interface ensures your model has the required methods to function as a stateable entity. This includes setting workflow attributes, state attributes, and metadata attributes. You can also determine supported workflows, apply workflows, and make transitions. Below are sample usages:

```
use AuroraWebSoftware\ArFlow\Contacts\StateableModelContract;

class YourModel extends Model implements StateableModelContract
{
    use HasState;

    public static function supportedWorkflows(): array
    {
        return ['workflow1', 'workflow3'];
    }

    // Your model properties and methods
}
```

3. (Optional) Define the workflow-related attributes for your model in the model class if you want to change default values or skip this step:

```
class YourModel extends Model implements StateableModelContract
{
    use HasState;

    public static function workflowAttribute(): string
    {
        return 'workflow';
    }

    public static function stateAttribute(): string
    {
        return 'state';
    }

    public static function stateMetadataAttribute(): string
    {
        return 'state_metadata';
    }

    // Your model properties and methods
}
```

### Usage

[](#usage)

Now that you've set up your model, you can apply workflows and perform transitions:

#### Applying a Workflow

[](#applying-a-workflow)

To apply a workflow to a model instance, use the `applyWorkflow` method:

```
$model = YourModel::find($id);
$model->applyWorkflow('workflow_name');
```

#### To get the current workflow of a model:

[](#to-get-the-current-workflow-of-a-model)

```
$currentWorkflow = $instance->currentWorkflow();
```

#### To get the current state of a model:

[](#to-get-the-current-state-of-a-model)

```
$currentState = $instance->currentState();
```

### Checking Transition States

[](#checking-transition-states)

You can check if a transition to a specific state is allowed using the `canTransitionTo` method:

```
$model = YourModel::find($id);
if ($model->canTransitionTo('new_state')) {
    // Transition is allowed
} else {
    // Transition is not allowed
}
```

#### Transitioning to a State

[](#transitioning-to-a-state)

To transition a model to a new state, use the `transitionTo` method:

```
$model = YourModel::find($id);
$model->transitionTo('new_state');
```

### Getting Defined and Allowed Transition States

[](#getting-defined-and-allowed-transition-states)

You can retrieve the defined and allowed transition states for a model:

```
// Defined transition states
$definedStates = $model->definedTransitionStates();

// Allowed transition states
$allowedStates = $model->allowedTransitionStates();
```

### TransitionGuardResults

[](#transitionguardresults)

You can also get transition guard results using the `transitionGuardResults` method:

```
$results = $model->transitionGuardResults('new_state');
```

This method returns a collection of transition guard results, which can be used to check if guards allow the transition.

### Configuration

[](#configuration)

You can configure your workflows in the `config/arflow.php` file. Define your workflows, states, transitions, guards, and actions there.

### Sample Configuration

[](#sample-configuration)

Here's a sample configuration for a workflow:

### Blueprint Macro

[](#blueprint-macro)

To simplify adding state columns to your migrations, a Blueprint macro is provided: This macro `$table->arflow()` will create three columns: workflow, state, and state\_metadata.

```
// your_migration.php
Schema::create('your_model', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->arflow();
    $table->timestamps();
});
```

```
// config/arflow.php
return [
    'workflows' => [
        'workflow_name' => [
            'states' => ['state1', 'state2', 'state3'],
            'initial_state' => 'state1',
            'transitions' => [
                'transition_name' => [
                    'from' => ['state1'],
                    'to' => 'state2',
                    'guards' => [
                        [GuardClass::class, ['permission' => 'approval']],
                    ],
                    'actions' => [
                        [ActionClass::class, ['param1' => 'value1']],
                    ],
                    'success_metadata' => ['key' => 'value'],
                    'success_jobs' => [JobClass::class],
                ],
                // Define more transitions as needed
            ],
        ],
        // Define additional workflows
    ]
];
```

### Creating Transition Guards

[](#creating-transition-guards)

Sample Transition Guard Implementation.

```
namespace App\ArFlow\Guards;

use AuroraWebSoftware\ArFlow\Contacts\StateableModelContract;
use AuroraWebSoftware\ArFlow\Contacts\TransitionGuardContract;
use AuroraWebSoftware\ArFlow\DTOs\TransitionGuardResultDTO;

class PermissionTransitionGuard implements TransitionGuardContract
{
    private StateableModelContract $model;
    private string $from;
    private string $to;
    private array $parameters;

    public function __construct() {}

    public function boot(StateableModelContract &Model $model, string $from, string $to, array $parameters): void
    {
        $this->model = $model;
        $this->from = $from;
        $this->to = $to;
        $this->parameters = $parameters;

        // You can perform any initialization here.
    }

    public function handle(): TransitionGuardResultDTO
    {
        // Implement your logic to check permissions here.
        // For example, check if the user has the required role to make the transition.

        // If the permission check passes, allow the transition:
        return TransitionGuardResultDTO::build(TransitionGuardResultDTO::ALLOWED);

        // If the permission check fails, deny the transition:
        // return TransitionGuardResultDTO::build(TransitionGuardResultDTO::DENIED, 'Permission denied.');
    }
}
```

### Creating Transition Action

[](#creating-transition-action)

Sample Transition Action

```
use AuroraWebSoftware\ArFlow\Contacts\TransitionActionContract;

class SendNotificationAction implements TransitionActionContract
{
    public function boot(StateableModelContract&Model $model, string $from, string $to, array $parameters = []): void {}

    public function handle(): void
    {
        // Send a notification when the transition is successful.
    }

    public function failed(): void
    {
        // Handle any cleanup or error logging here if the action fails.
    }
}
```

### Creating Transition Success Job

[](#creating-transition-success-job)

Sample Transition Job

```
namespace AuroraWebSoftware\ArFlow\Tests\Jobs;

use AuroraWebSoftware\ArFlow\Abstracts\AbstractTransitionSuccessJob;
use AuroraWebSoftware\ArFlow\Contacts\StateableModelContract;
use Illuminate\Database\Eloquent\Model;

class TestTransitionSuccessJob extends AbstractTransitionSuccessJob
{
    /**
     * Execute the job.
     * @param StateableModelContract&Model $model
     * @param string $from
     * @param string $to
     * @param array $parameters
     */
    public function handle(StateableModelContract & Model $model, string $from, string $to, array $parameters = []): void
    {
        // Process
    }
}
```

Contribution
------------

[](#contribution)

- php 8.2+

```
docker-compose up -d
```

```
composer format
composer analyse
composer test
composer test-coverage
```

---

This documentation should help you get started with the ArFlow package in your Laravel application. Feel free to explore more features and configurations based on your project's requirements.

For more information, please refer to the package's GitHub repository or contact us for support.

###  Health Score

50

—

FairBetter than 96% of packages

Maintenance70

Regular maintenance activity

Popularity30

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 74.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~59 days

Recently: every ~50 days

Total

14

Last Release

174d ago

Major Versions

1.1.3 → 11.0.02024-12-11

11.0.0 → 12.0.02025-05-07

PHP version history (3 changes)1.0.0PHP ^8.2

11.0.0PHP ^8.2|^8.3

12.0.0PHP ^8.2|^8.3|^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/e79935c219efe1a3132a4c9f2b87da38268fccacfcb43c453275ceafdd1ed23f?d=identicon)[emreakay](/maintainers/emreakay)

---

Top Contributors

[![emreakay](https://avatars.githubusercontent.com/u/794216?v=4)](https://github.com/emreakay "emreakay (32 commits)")[![akiftezcan38](https://avatars.githubusercontent.com/u/77398471?v=4)](https://github.com/akiftezcan38 "akiftezcan38 (9 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")

---

Tags

laravellaravelAuroraWebSoftwarearflow

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/aurorawebsoftware-arflow/health.svg)

```
[![Health](https://phpackages.com/badges/aurorawebsoftware-arflow/health.svg)](https://phpackages.com/packages/aurorawebsoftware-arflow)
```

###  Alternatives

[laravel/nightwatch

The official Laravel Nightwatch package.

3526.1M13](/packages/laravel-nightwatch)[bezhansalleh/filament-plugin-essentials

A collection of essential traits that streamline Filament plugin development by taking care of the boilerplate, so you can focus on shipping real features faster

27584.7k16](/packages/bezhansalleh-filament-plugin-essentials)[codewithdennis/larament

Larament is a time-saving starter kit to quickly launch Laravel 13.x projects. It includes FilamentPHP 5.x pre-installed and configured, along with additional tools and features to streamline your development workflow.

3691.5k](/packages/codewithdennis-larament)[kompo/kompo

Laravel & Vue.js FullStack Components for Rapid Application Development

11812.4k21](/packages/kompo-kompo)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)