Download the PHP package jasperfernandez/laraflow without Composer

jasperfernandez/laraflow

Laraflow is a workflow engine for Laravel applications. It lets you define workflow templates with ordered steps, assign roles to each step, configure allowed actions, and run workflow instances against any Eloquent model.

It is a good fit for application flows such as membership approvals, onboarding, request routing, document review, or any process that needs step history, assignments, status transitions, and audit trails.

Installation

Install the package with Composer:

Publish and run the package migrations:

Publish the config file:

Before You Start

Laraflow manages workflow templates, workflow instances, workflow steps, assignments, and transitions. Your application is responsible for the domain records that Laraflow references:

• roles
• statuses
• actions
• the subject model you want to attach a workflow to

By default, the package checks whether the acting user can execute a step by calling hasRole(string $role) on the authenticated user model. If your user model does not expose that method, the default authorization will deny the action.

Configuration

After publishing the config, point the package at your own role, status, and action models:

Your application models should provide these fields:

• Role: id, name
• Status: id, code, name
• Action: id, code, name

Defining A Workflow

A workflow is defined with four main records:

1. A WorkflowTemplate
2. One or more WorkflowTemplateStep records
3. One or more WorkflowTemplateStepAssignment records that assign roles to each step
4. One or more WorkflowTemplateStepAction records that define which actions are allowed and where they lead

Example:

Starting A Workflow

Use WorkflowEngine::start() to create a workflow instance for any Eloquent model:

When a workflow starts, Laraflow:

• resolves the active template by template_code
• picks the lowest step sequence_no
• creates a workflow instance
• opens the first runtime step
• creates runtime assignments for the valid roles on that step

Applying An Action

Use WorkflowEngine::apply() to execute an action on the current step:

The returned TransitionResult includes:

• instance: the updated workflow instance
• fromStep: the step that was acted on
• toStep: the next opened step, or null if the workflow was closed
• transition: the recorded transition row
• closed: whether the workflow is now closed

Authorization

The default authorization strategy is role-based. The package checks the assigned role names on the current step and calls hasRole() on the actor.

Example:

If you want a different authorization strategy, bind your own implementation of JasperFernandez\Laraflow\Contracts\WorkflowAuthorization in your application container.

End-To-End Example

Subject Integration

To easily manage workflows on your models, use the HasWorkflows trait:

Events

Laraflow dispatches the following events during the workflow lifecycle:

You can listen to these events in your EventServiceProvider:

Notes

• Use WorkflowEngine as the main entry point.
• The package can attach workflows to any Eloquent model through Laravel morph relationships.
• Workflow definitions are loaded from the database through the default repository implementation.
• Inactive workflow templates are ignored.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Jasper Fernandez

License

The MIT License (MIT). Please see LICENSE.md for more information.