Download the PHP package aurorawebsoftware/arflow without Composer

ArFlow Workflow and State Machine Laravel Package Documentation

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

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

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

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

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

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

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

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

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

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

don't forget to run the migration:

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.

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:

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:

Usage

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

Applying a Workflow

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

To get the current workflow of a model:

To get the current state of a model:

`

Checking Transition States

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

Transitioning to a State

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

Getting Defined and Allowed Transition States

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

TransitionGuardResults

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

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

Configuration

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

Sample Configuration

Here's a sample configuration for a workflow:

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.

Creating Transition Guards

Sample Transition Guard Implementation.

Creating Transition Action

Sample Transition Action

Creating Transition Success Job

Sample Transition Job

Contribution

• php 8.2+

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.