Download the PHP package mrnewport/laravel-flow without Composer

mrnewport/laravel-flow

A domain-agnostic flow/workflow package for Laravel. It allows:

• FlowStep definitions with optional assignment strategies and notifications.
• FlowTransition actions that link one step to the next.
• FlowInstance tracking each entity’s position in the flow.
• FlowInstanceStep logging each step taken by that entity.
• A pivot-based assignment table (flow_step_assignees), so you can assign one or many users or external emails.
• Reassign logic if someone else needs to handle the step.
• Multi-step transitions (one action can lead to multiple next steps).
• Laravel events and notifications for each action.

Everything is infinitely expandable—with no forced domain or role logic. Perfect for multi-approval flows, complex multi-step processes, or advanced e-sign style flows.

Table of Contents

1. Requirements
2. Installation
3. Configuration
4. Database Structure
5. Core Concepts
   • FlowStep
   • FlowTransition
   • FlowInstance
   • FlowInstanceStep
   • FlowStepAssignee
6. Assignment Strategies
   • SingleUserStrategy
   • MultiUserStrategy
   • EmailListStrategy
   • Reassigning a Step
7. Using the FlowManager
   • Multi-Step Example with More Steps
   • Starting a Flow
   • Completing a Step with an Action
   • Multiple Transitions
   • End Step
   • Events
   • Notifications
8. Console Commands
   • DefineStepCommand
9. Flowable Trait
10. Advanced Customization
    • 1. Custom Assignment Strategies
    • 2. Event Listeners for Step+Action Logic
    • 3. Larger Example: 6+ Steps, Complex Branching
    • 4. Rejection Actions and External Approvals
    • 5. Integrating with External Services
    • 6. Additional Notifications & Channels
11. Testing
12. License

Requirements

• Laravel ^11.0
• PHP ^8.1
• Illuminate (events, notifications, database)
• spatie/laravel-package-tools ^1.9

Installation

1. Install via Composer:

2. (Optional) Publish config & stubs:

3. Migrate:

   This creates flow_steps, flow_transitions, flow_instances, flow_instance_steps, and flow_step_assignees.

Configuration

After publishing, open config/flow.php:

• user_model: If your assignment strategies reference Eloquent users, update here.
• rejection_actions: Flow actions that count as rejections/cancellations.

Database Structure

1. flow_steps: Each distinct step.

   • id: The string identifier.
   • name: A descriptive title.
   • notify: If true, the system can automatically handle notifications.
   • assignment_strategy: e.g. 'single_user', 'multi_user', 'email_list'
   • assignment_params: JSON object for that strategy.

2. flow_transitions: Action-based transitions.

   • step_id: The current step’s ID.
   • action: e.g. 'approve', 'reject', 'submit'.
   • next_step_id: The next step triggered by that action.

3. flow_instances: Tracks which step a particular model is on.

   • current_step_id: The step the entity is currently at.
   • model_type, model_id: Polymorphic references to your Eloquent model (e.g. App\Models\Post).

4. flow_instance_steps: Log of each step in a particular instance.

   • flow_instance_id: references the flow_instances row.
   • step_id: references flow_steps.
   • action_taken: the action used to complete the step, if any.
   • started_at, finished_at: timestamps.
5. flow_step_assignees: Pivot storing who must do a step.
   • flow_instance_step_id: The instance step that’s assigned.
   • assignee_type: 'user', 'email', 'token', etc.
   • assignee_value: The user ID, email address, or external reference.

Core Concepts

FlowStep

An individual step in your flow. Example IDs: 'draft_review', 'supplier_upload', 'marketing_approval'. Each step can specify:

• notify: If true, the system or an event listener can trigger notifications automatically.
• assignment_strategy, assignment_params: e.g. 'single_user' with {"user_id":8}.

FlowTransition

Defines an action from step_id → next_step_id. For example, (draft_review, 'approve', marketing_approval) means if user approves at draft_review, the next step is marketing_approval.

FlowInstance

Records which step a specific entity (like a post, application, or user-submitted form) is currently at. Also references all steps that have been completed in flow_instance_steps.

FlowInstanceStep

A record of a step within a FlowInstance. We store the timestamps and the action that completed it. If the step has an assignment strategy, it’s also assigned to users/emails in flow_step_assignees.

FlowStepAssignee

Pivot that stores exactly who’s assigned to a step. For instance, 'assignee_type=user', 'assignee_value=3' means user #3 must handle it.

Assignment Strategies

The package includes SingleUserStrategy, MultiUserStrategy, and EmailListStrategy. They all implement AssignmentStrategyInterface, auto-populating flow_step_assignees whenever a new step is created.

SingleUserStrategy

• assignment_params={"user_id":7}
• Creates a single pivot row: (flow_instance_step_id, 'user', '7').

MultiUserStrategy

• assignment_params={"user_ids":[7,8]}
• Creates multiple pivot rows for each user ID.

EmailListStrategy

• assignment_params={"emails":["[email protected]","[email protected]"]}
• Creates pivot rows with 'assignee_type=email', 'assignee_value="[email protected]" etc.

Reassigning a Step

Use:

• Checks if the strategy’s canReassign($step, $currentUser) is true, then calls reassign($step, $newAssignees).
• If it’s single-user strategy, we remove the old assignment, add the new. If multi-user, we remove or update accordingly.

Using the FlowManager

Below are typical calls to FlowManager.

Multi-Step Example with More Steps

Let’s define these steps:

1. start_request
2. manager_review
3. director_approval
4. supplier_upload
5. marketing_check
6. quality_assurance
7. END

We can have transitions like:

• (start_request, 'submit', manager_review)
• (manager_review, 'reject', start_request)
• (manager_review, 'approve', director_approval)
• (director_approval, 'approve', supplier_upload)
• (director_approval, 'reject', manager_review)
• (supplier_upload, 'upload_done', marketing_check)
• (marketing_check, 'changes_needed', supplier_upload)
• (marketing_check, 'approve', quality_assurance)
• (quality_assurance, 'approve', END)
• (quality_assurance, 'reject', supplier_upload)

This means your flow can bounce around multiple times if rejections occur.

Starting a Flow

1. Define your step with flow:define-step or code. For example:

   Next define transitions:

2. In your code:

Completing a Step with an Action

• If (start_request, 'submit') => manager_review transition exists, a new FlowInstanceStep is created for manager_review, assigned if needed, and current_step_id updates to 'manager_review'.

Multiple Transitions

One (step_id, action) can lead to multiple next_step_id:

Now calling:

Creates three new steps: stepX, stepY, stepZ.

End Step

If a transition’s next_step_id='END', that signals the flow is finished. FlowInstance is updated to current_step_id='END', no further steps.

Events

When you call:

a FlowActionEvent($oldStep, 'approve', $newStepOrNull) is fired. Use standard Laravel event listeners to add custom logic or extra notifications.

Notifications

If flow_steps.notify==true, you can have your listeners automatically send out FlowBaseNotification or custom notifications to the assigned users/emails. Typically:

• Check flow_step_assignees for that step.
• If 'assignee_type=user', load the user’s Eloquent record from config('flow.user_model').
• If 'assignee_type=email', route a mail-based notification.

Console Commands

DefineStepCommand

Use this command to create or update a step and define transitions in one shot:

Prints lines for each transition, then:

Flowable Trait

If you want to manage flows directly from an Eloquent model, you can:

Then:

No direct calls to FlowManager.

Advanced Customization

Below are expansion ideas purely through your own code (events, custom classes).

1. Custom Assignment Strategies

If your domain requires specialized logic—like a Token or Slack approach—create a class implementing AssignmentStrategyInterface:

Then reference 'slack_channel' in your step’s assignment_strategy and 'assignment_params'=>{"channel":"#my-team"}.

2. Event Listeners for Step+Action Logic

Whenever FlowManager::actionStep($oldStep, 'approve') is called, a FlowActionEvent fires. You can define a listener:

No need to modify package code—you handle domain logic in your event listener.

3. Larger Example: 6+ Steps, Complex Branching

Suppose you define these steps: stepA, stepB, stepC, stepD, stepE, stepF, and END. You can do:

Now you have a multi-branch flow with looping between stepB/stepD if rejections happen, or skipping stepB by going stepA → skip → stepC. No domain constraints, purely structured in your transitions.

4. Rejection Actions and External Approvals

If you set config('flow.rejection_actions')=['reject','cancel'], any step completed with 'reject' or 'cancel' is considered a rejection. You can add a step for 'supplier_upload' with transitions 'action=reject => rework_assets'. That flow logic is fully under your control. If you want external e-sign or approval, store the token or link in assignment_params and let the user finalize externally.

5. Integrating with External Services

Each time a new step is created, you could:

• Post to Slack with the assigned user info.
• Call an external DocuSign or HelloSign API to request a signature.
• Send events to a microservice queue.

All done in your listeners or custom code that runs upon step creation.

6. Additional Notifications & Channels

FlowBaseNotification is a mail-based example. You can define:

• FlowSlackNotification: via() returns [SlackChannel::class], posting a Slack message.
• FlowSmsNotification: using Twilio or Nexmo.
• No changes in the package are required. You just create these in your app code and send them from an event listener or a custom approach.

Testing

A comprehensive test suite lives in tests/. Just run:

It covers:

• DefineStepCommandTest: verifying creation of steps & transitions with exact console output.
• FlowManagerBasicTest: tests startFlow & single-step transitions.
• FlowManagerAssignmentTest: ensures assignment & reassign logic works.
• FlowManagerMultiTransitionsTest: multiple next steps for one action.
• FlowEventTest: verifies FlowActionEvent is fired.
• FlowNotificationTest: demonstrates how notifications can be triggered for assigned users/emails.

License

This package is open-sourced software licensed under the MIT license. Enjoy building fully domain-agnostic flows for your Laravel application!