Download the PHP package juststeveking/laravel-flows without Composer

Laravel Flows

A fluent, modular workflow builder for Laravel that leverages the Pipeline pattern to simplify and organize business logic.

Introduction

Flows is a lightweight Laravel package designed to turn complex, multi-step business logic into an elegant, maintainable workflow. With a fluent API, you can easily chain steps, incorporate conditional logic, and keep your code modular and testable—perfect for any process that needs a well-orchestrated flow.

Features

• Fluent API: Easily chain workflow steps using methods like run(), branch(), chain(), and the new runIf().
• Conditional Branches: Integrate custom conditions using your own implementations of FlowCondition.
• Testable & Modular: Each step is isolated, making it a breeze to unit test and maintain.

Installation

Install the package via composer:

Usage

Basic Usage

Create a simple workflow to process your payload:

Advanced Workflow with Conditional Branches

Leverage branch steps to conditionally execute parts of your workflow:

Real-World Example: User Registration

The workflow starts with basic tasks: validating the registration data, hashing the password, creating the user, and sending a welcome email.

It then uses a branch to conditionally run a sub-workflow (sending a VIP welcome email) if the condition IsVIPUser evaluates to true.

Finally, it logs the registration event before returning the processed data.

How to use this package

This package defines a couple of core interfaces that helps you to build consistent, testable, and modular workflows. By implementing these interfaces, you ensure that every step and condition in your workflow follows a predictable contract.

FlowStep Interface

The FlowStep interface ensures that every workflow step implements a standard handle method. This method receives a payload and a closure representing the next step. This makes it super easy to chain multiple actions together.

Interface Definition

Usage Example

WHen creating a new workflow step (for instance, validating registration data), simply implement the interface:

FlowCondition Interface

The FlowCondition interface standardizes how conditional logic is implemented in your workflows. Each condition must be invokable (using the __invoke method) and return a boolean based on the payload. This way, you can easily decide if a branch should execute.

Interface Definition:

Usage Example:

For example, to check if a user is VIP:

Automatic Step Skipping

Instead of embedding skip logic within each step, you can use the runIf() method to automatically skip steps based on a condition. This method takes a callable condition and an action. If the condition evaluates to true, the step executes; otherwise, it is skipped.

Catching Exceptions

The catch method allows you to handle exceptions that occur during the flow execution. You can add error handling logic that will intercept any exceptions thrown by previous steps in the flow.

Example with Error Logging:

Putting It All Together

When defining your workflows, you can mix and match steps and conditions seamlessly. Use run() or chain() for your steps and branch() for conditionally running sub-flows. This keeps your business logic clean and flexible.

Reusable Flow

The ->with(...) method in a flow offers you the flexibility you need to specify flow logic that can be re-used wherever you need it.

Example with Reusable Flow:

The ->with(...) method accepts any form of callable, such as:

• Closures (e.g. function () { })
• Traditional callable notations (e.g. [$this, 'methodName'])
• First-class callables (e.g. $this->methodName(...))
• Invokable classes (e.g. a class with the __invoke magic method)
• Whatever else PHP defines as callable.

Example Usage

By following these interfaces, every step in your workflow will have a consistent contract, making your code more robust, maintainable, and easier to test.

Debugging & Logging

The debug() method lets you inject a PSR-3 compatible logger (such as the Laravel built-in logger) into your workflow. When a logger is set, the Flow class automatically wraps each step with logging calls, which log the payload before and after each step is executed. This is invaluable for debugging complex workflows, as it gives you clear insights into how the data transforms throughout the process.

How it Works

When you call debug(), the Flow instance stores the provided logger. Then, in the execute() method, if a logger is present, it wraps every step in a closure that:

• Logs a “Before step:” message along with the current payload.
• Executes the step (whether it’s a class or a closure).
• Logs an “After step:” message along with the result from the step.

This logging mechanism happens automatically without modifying your individual step logic, so you can focus on business logic and easily troubleshoot the execution flow.

Example Usage

With the logger enabled, you’ll see log entries like:

• Before step: "Before step: App\Flows\Steps\HashPassword" with the current payload.
• After step: "After step: App\Flows\Steps\HashPassword" with the transformed payload.

This feature is especially useful during development and troubleshooting, as it helps you track the data transformations throughout your workflow.

Architecture Diagram

Testing

This package comes fully unit tested. To run the tests:

Contributing

Contributions are welcome! Please submit a pull request or open an issue if you encounter bugs or have ideas for improvements. Follow PET coding standards for consistency, this is automated using Laravel Pint and composer run pint.

License

This package is open-sourced software licensed under the MIT license.