PHPackages                             kumogire/laravel-workflow - 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. kumogire/laravel-workflow

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

kumogire/laravel-workflow
=========================

A flexible workflow system for Laravel applications

v1.3.0(1mo ago)03MITPHPPHP ^8.2|^8.3

Since Feb 6Pushed 1mo agoCompare

[ Source](https://github.com/kumogire/laravel-workflow)[ Packagist](https://packagist.org/packages/kumogire/laravel-workflow)[ RSS](/packages/kumogire-laravel-workflow/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (8)Versions (5)Used By (0)

Laravel Workflow
================

[](#laravel-workflow)

[![Latest Version on Packagist](https://camo.githubusercontent.com/d4b25cdf43e2aa7a1b60f8f5daae89309cdb70df729418e3bf5a562cef8ad500/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b756d6f676972652f6c61726176656c2d776f726b666c6f772e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/kumogire/laravel-workflow)[![Total Downloads](https://camo.githubusercontent.com/20dabaf53d780f616f813fb91496589a74163907bddeb44b2efd1638f1c6677b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6b756d6f676972652f6c61726176656c2d776f726b666c6f772e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/kumogire/laravel-workflow)[![License](https://camo.githubusercontent.com/9d4ab5e378641f143bca90a224840ad808245df5247f20c30d2f942e0c245dac/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6b756d6f676972652f6c61726176656c2d776f726b666c6f772e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/kumogire/laravel-workflow)

A flexible, database-driven workflow system for Laravel applications.

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

[](#installation)

```
composer require kumogire/laravel-workflow
```

Run the installation command:

```
php artisan workflow:install
```

This will publish the configuration file and run the database migrations.

Configuration
-------------

[](#configuration)

The configuration file is published to `config/workflow.php`. You can customize:

- User model
- Route prefixes and middleware
- Action handlers
- Queue settings
- Cache settings

To manually publish the configuration:

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

Basic Usage
-----------

[](#basic-usage)

### Using the Workflow Facade

[](#using-the-workflow-facade)

The package automatically registers the `Workflow` facade for convenient access.

```
use Kumogire\Workflow\Facades\Workflow;
use Kumogire\Workflow\Models\Workflow as WorkflowModel;

// Get a workflow
$workflow = WorkflowModel::find(1);
$user = auth()->user();

// Start a workflow instance
$instance = Workflow::startWorkflow($workflow, $user);

// Complete the current step
$instance = Workflow::completeStep($instance, $user, [
    'answer' => 'yes',
    'score' => 85,
]);

// Get current step details
$details = Workflow::getCurrentStepDetails($instance, $user);

// Manage workflow state
Workflow::pauseWorkflow($instance);
Workflow::resumeWorkflow($instance);
Workflow::abandonWorkflow($instance);
```

### Using Dependency Injection

[](#using-dependency-injection)

You can also inject the service directly into your controllers or classes:

```
use Kumogire\Workflow\Services\WorkflowService;

class OnboardingController extends Controller
{
    public function __construct(
        protected WorkflowService $workflowService
    ) {}

    public function start(Workflow $workflow)
    {
        $instance = $this->workflowService->startWorkflow(
            $workflow,
            auth()->user()
        );

        return response()->json($instance);
    }

    public function completeStep(WorkflowInstance $instance, Request $request)
    {
        $instance = $this->workflowService->completeStep(
            $instance,
            auth()->user(),
            $request->validated()
        );

        return response()->json($instance);
    }
}
```

### Creating Workflows

[](#creating-workflows)

Create workflows programmatically or through your admin interface:

```
use Kumogire\Workflow\Models\Workflow;
use Kumogire\Workflow\Models\WorkflowStep;

$workflow = Workflow::create([
    'name' => 'Employee Onboarding',
    'description' => 'Complete onboarding process for new employees',
    'type' => 'onboarding',
    'is_active' => true,
]);

// Add steps
WorkflowStep::create([
    'workflow_id' => $workflow->id,
    'order' => 1,
    'title' => 'Complete Profile',
    'description' => 'Fill out your employee profile',
    'type' => 'form',
    'configuration' => [
        'fields' => ['name', 'phone', 'address']
    ],
    'can_complete_roles' => ['employee'],
]);

WorkflowStep::create([
    'workflow_id' => $workflow->id,
    'order' => 2,
    'title' => 'Manager Approval',
    'description' => 'Wait for manager to approve your profile',
    'type' => 'approval',
    'can_complete_roles' => ['manager', 'admin'],
]);
```

Advanced Features
-----------------

[](#advanced-features)

### Conditional Steps

[](#conditional-steps)

Steps can be conditionally executed or skipped based on data:

```
WorkflowStep::create([
    'workflow_id' => $workflow->id,
    'order' => 3,
    'title' => 'Additional Training',
    'condition_type' => 'if_data_equals',
    'condition_config' => [
        'field' => 'department',
        'value' => 'engineering'
    ],
    'skip_if_condition_false' => true,
]);
```

**Available condition types:**

- `always` - Always execute (default)
- `if_data_equals` - Check if field equals value
- `if_data_contains` - Check if array field contains value
- `if_role` - Check if user has specific role

### Step Permissions

[](#step-permissions)

Control who can view and complete each step:

```
WorkflowStep::create([
    'workflow_id' => $workflow->id,
    'order' => 1,
    'title' => 'HR Review',
    'can_view_roles' => ['hr', 'admin'],
    'can_complete_roles' => ['hr', 'admin'],
]);
```

Empty role arrays mean any authenticated user can access the step.

### Workflow Actions

[](#workflow-actions)

Actions trigger automatically when steps start or complete:

```
use Kumogire\Workflow\Models\WorkflowAction;

WorkflowAction::create([
    'workflow_step_id' => $step->id,
    'type' => 'email',
    'trigger' => 'on_step_complete',
    'configuration' => [
        'to' => '{{user.email}}',
        'template' => 'onboarding-welcome',
        'subject' => 'Welcome aboard!',
    ],
]);
```

**Built-in action types:**

- `email` - Send email notifications
- `sms` - Send SMS messages
- `webhook` - Call external webhooks
- `data_save` - Save data to database

**Trigger points:**

- `on_step_start` - When step begins
- `on_step_complete` - When step is completed

Customization
-------------

[](#customization)

### Custom Action Handlers

[](#custom-action-handlers)

Create custom action handlers for specific integrations:

```
namespace App\Workflow\Actions;

use Kumogire\Workflow\Contracts\ActionHandler;
use Kumogire\Workflow\Models\WorkflowAction;
use Kumogire\Workflow\Models\WorkflowInstance;

class SlackNotificationHandler implements ActionHandler
{
    public function handle(WorkflowAction $action, WorkflowInstance $instance): void
    {
        $config = $action->configuration;
        $channel = $config['channel'] ?? '#general';
        $message = $config['message'] ?? 'Workflow notification';

        // Send to Slack
        // \Slack::send($channel, $message);
    }
}
```

Register your custom handler in `config/workflow.php`:

```
'action_handlers' => [
    'email' => \Kumogire\Workflow\Actions\Handlers\EmailActionHandler::class,
    'sms' => \Kumogire\Workflow\Actions\Handlers\SmsActionHandler::class,
    'webhook' => \Kumogire\Workflow\Actions\Handlers\WebhookActionHandler::class,
    'data_save' => \Kumogire\Workflow\Actions\Handlers\DataSaveActionHandler::class,
    'slack' => \App\Workflow\Actions\SlackNotificationHandler::class, // Your custom handler
],
```

### Events

[](#events)

The package dispatches events you can listen to:

- `WorkflowStarted` - When a workflow instance begins
- `StepStarted` - When a step is entered
- `StepCompleted` - When a step is finished
- `WorkflowCompleted` - When all steps are done
- `WorkflowPaused` - When a workflow is paused
- `WorkflowAbandoned` - When a workflow is cancelled

Example listener:

```
namespace App\Listeners;

use Kumogire\Workflow\Events\WorkflowCompleted;

class SendCompletionNotification
{
    public function handle(WorkflowCompleted $event)
    {
        $instance = $event->instance;
        $user = $instance->user;

        // Send notification
        $user->notify(new WorkflowCompletedNotification($instance));
    }
}
```

### Extending Models

[](#extending-models)

You can extend the package models if needed:

```
namespace App\Models;

use Kumogire\Workflow\Models\Workflow as BaseWorkflow;

class Workflow extends BaseWorkflow
{
    // Add custom methods or relationships
    public function department()
    {
        return $this->belongsTo(Department::class);
    }
}
```

Then update `config/workflow.php`:

```
'models' => [
    'workflow' => \App\Models\Workflow::class,
],
```

Workflow Action Examples
------------------------

[](#workflow-action-examples)

### Email Action

[](#email-action)

```
use Kumogire\Workflow\Models\WorkflowAction;

WorkflowAction::create([
    'workflow_step_id' => $step->id,
    'type' => 'email',
    'trigger' => 'on_step_complete',
    'configuration' => [
        'to' => '{{user.email}}',
        'subject' => 'Welcome to {{workflow.name}}!',
        'template' => 'emails.workflow.welcome',
        'data' => [
            'user_name' => '{{user.name}}',
            'workflow_name' => '{{workflow.name}}',
        ],
    ],
]);

```

### SMS Action

[](#sms-action)

```
WorkflowAction::create([
    'workflow_step_id' => $step->id,
    'type' => 'sms',
    'trigger' => 'on_step_start',
    'configuration' => [
        'to' => '{{user.phone}}',
        'message' => 'Hi {{user.name}}, your next step is ready!',
    ],
]);

```

### Webhook Action

[](#webhook-action)

```
WorkflowAction::create([
    'workflow_step_id' => $step->id,
    'type' => 'webhook',
    'trigger' => 'on_step_complete',
    'configuration' => [
        'url' => 'https://api.example.com/workflow-notifications',
        'method' => 'POST',
        'headers' => [
            'Authorization' => 'Bearer YOUR_API_KEY',
            'Content-Type' => 'application/json',
        ],
        'payload' => [
            'user_id' => '{{user.id}}',
            'workflow_id' => '{{workflow.id}}',
            'step_completed' => true,
        ],
    ],
]);

```

### Data Save Action

[](#data-save-action)

```
WorkflowAction::create([
    'workflow_step_id' => $step->id,
    'type' => 'data_save',
    'trigger' => 'on_step_complete',
    'configuration' => [
        'model' => 'App\Models\UserProfile',
        'find_by' => [
            'user_id' => '{{user.id}}',
        ],
        'attributes' => [
            'onboarding_completed' => true,
            'completed_at' => now(),
        ],
    ],
]);

```

API Endpoints
-------------

[](#api-endpoints)

The package provides RESTful API endpoints (configurable via `config/workflow.php`):

```
GET    /api/workflows                    - List available workflows
GET    /api/workflows/{workflow}          - Get workflow details
POST   /api/workflow-instances            - Start a new workflow instance
GET    /api/workflow-instances/{instance} - Get instance details
POST   /api/workflow-instances/{instance}/complete-step - Complete current step
GET    /api/workflow-instances/user/{user} - List user's workflows

```

API Usage Examples
------------------

[](#api-usage-examples)

### Start a Workflow

[](#start-a-workflow)

```
POST /api/workflows/instances
{
    "workflow_id": 1,
    "metadata": {
        "department": "engineering"
    }
}

```

### Get Current Step

[](#get-current-step)

```
GET /api/workflows/instances/1
Response:
json{
    "instance_id": 1,
    "status": "in_progress",
    "current_step": {
        "id": 2,
        "title": "Complete Profile",
        "description": "Fill out your details",
        "type": "form",
        "configuration": {
            "fields": ["name", "phone", "address"]
        },
        "can_view": true,
        "can_complete": true
    },
    "workflow": {
        "id": 1,
        "name": "Employee Onboarding",
        "type": "onboarding"
    }
}

```

### Complete Step

[](#complete-step)

```
POST /api/workflows/instances/1/complete-step
{
    "data": {
        "name": "John Doe",
        "phone": "555-1234",
        "address": "123 Main St"
    }
}

```

### Admin: Create Workflow

[](#admin-create-workflow)

```
POST /admin/workflows/workflows
{
    "name": "Employee Onboarding",
    "description": "Complete onboarding process",
    "type": "onboarding",
    "is_active": true
}

```

### Admin: Create Step

[](#admin-create-step)

```
POST /admin/workflows/steps
{
    "workflow_id": 1,
    "order": 1,
    "title": "Complete Profile",
    "type": "form",
    "configuration": {
        "fields": ["name", "email", "phone"]
    },
    "can_complete_roles": ["employee"]
}

```

API Documentation
-----------------

[](#api-documentation)

Full API documentation is available in multiple formats:

- [Markdown Documentation](docs/API.md)
- [OpenAPI Specification](docs/openapi.yaml) - Import into Swagger UI
- [Postman Collection](docs/postman_collection.json) - Import into Postman

### Quick Start with Postman

[](#quick-start-with-postman)

1. Download the [Postman collection](docs/postman_collection.json)
2. Import into Postman
3. Set your `base_url` and `bearer_token` variables
4. Start making requests!

Admin View Componets
--------------------

[](#admin-view-componets)

### Example: Dashboard with widgets

[](#example-dashboard-with-widgets)

```
{{-- In project's resources/views/admin/dashboard.blade.php --}}
@extends('layouts.admin')

@section('content')

        {{-- Statistics --}}

            {{-- Recent workflows --}}

            {{-- User's active workflows --}}

@endsection

```

### Example: Workflow management page

[](#example-workflow-management-page)

```
{{-- In parent project's resources/views/admin/workflows.blade.php --}}
@extends('layouts.admin')

@section('content')
    {{-- List all workflows --}}

    {{-- Or filter by type --}}

    {{-- Show inactive workflows too --}}

@endsection

```

### Example: Create workflow form

[](#example-create-workflow-form)

```
{{-- In parent project's resources/views/admin/create-workflow.blade.php --}}
@extends('layouts.admin')

@section('content')

        Create Workflow

            {{-- Custom cancel button in the slot --}}

                Cancel

@endsection

```

### Example: View workflow with steps

[](#example-view-workflow-with-steps)

```
{{-- In parent project's resources/views/admin/view-workflow.blade.php --}}
@extends('layouts.admin')

@section('content')

        {{-- Workflow details --}}

            {{ $workflow->name }}
            {{ $workflow->description }}

        {{-- Steps with actions --}}

@endsection

```

Tests
-----

[](#tests)

Run all tests
=============

[](#run-all-tests)

composer test

Run specific test suite
=======================

[](#run-specific-test-suite)

vendor/bin/phpunit --testsuite Unit vendor/bin/phpunit --testsuite Feature

Run with coverage
=================

[](#run-with-coverage)

composer test-coverage# Run all tests composer test

Run specific test suite
=======================

[](#run-specific-test-suite-1)

vendor/bin/phpunit --testsuite Unit vendor/bin/phpunit --testsuite Feature

Run with coverage
=================

[](#run-with-coverage-1)

composer test-coverage

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Laravel 10.x or 11.x

License
-------

[](#license)

MIT

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance92

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~18 days

Total

4

Last Release

40d ago

PHP version history (2 changes)v1.1.1PHP ^8.1

v1.2.1PHP ^8.2|^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/769da8c01a5419247a4c442ce31290f53b4959aff5d659535bb0ab867945b8bc?d=identicon)[kumogire](/maintainers/kumogire)

---

Top Contributors

[![kumogire](https://avatars.githubusercontent.com/u/1085831?v=4)](https://github.com/kumogire "kumogire (25 commits)")

---

Tags

composer-packagelaravellaravel-packageprocessstate-machineworkflowlaravelprocessworkflowstate-machine

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/kumogire-laravel-workflow/health.svg)

```
[![Health](https://phpackages.com/badges/kumogire-laravel-workflow/health.svg)](https://phpackages.com/packages/kumogire-laravel-workflow)
```

###  Alternatives

[livewire/volt

An elegantly crafted functional API for Laravel Livewire.

4195.3M84](/packages/livewire-volt)[brexis/laravel-workflow

Integerate Symfony Workflow component into Laravel.

283125.6k](/packages/brexis-laravel-workflow)[ringierimu/state-workflow

Laravel State Workflow provide tools for defining and managing workflows and activities with ease.

3251.1k](/packages/ringierimu-state-workflow)[tarfin-labs/event-machine

Event-driven state machines for Laravel with event sourcing, type-safe context, and full audit trail.

188.5k](/packages/tarfin-labs-event-machine)[forxer/laravel-gravatar

A library providing easy gravatar integration in a Laravel project.

4235.6k](/packages/forxer-laravel-gravatar)

PHPackages © 2026

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