Download the PHP package imtiaz-hasan/flowforge without Composer

Flowforge

An n8n-style workflow automation engine for Laravel. Define triggers, actions, and branching flows in pure PHP.

Flowforge lets you wire up workflows out of small, connected nodes. A trigger starts a run, data flows from one node to the next, conditions branch the path, and every step is logged. It runs on your queue, retries failed steps, and is built to be extended with your own node types.

Why

n8n is great, but it lives outside your app. Flowforge keeps the automation inside your Laravel codebase: your models, your queue, your jobs, your tests. No separate service to host, no JSON exported from a visual editor that nobody can code-review. You define flows in PHP, commit them, and run them like any other part of the app.

Requirements

• PHP 8.2 or 8.3
• Laravel 11 or 12

Install

Publish and run the migrations:

Optionally publish the config:

Your first workflow in 5 lines

That registers a webhook-triggered workflow. POST to /flowforge/webhooks/welcome with {"email": "[email protected]"} and Flowforge starts a run on your queue, sends the email, and records the result.

Run a stored workflow by hand:

How it works

A workflow is a set of nodes keyed by id. Each node has a type, a config, and a link to the next node. The engine starts at the first node and walks the graph:

1. Resolve the node's config, filling in {{ placeholders }} from earlier output.
2. Run the node, retrying up to its configured number of attempts.
3. Write a node-run record (status, input, output, error, timing).
4. Follow the node's link, or a condition's branch, to the next node.

The whole run is one queued RunWorkflowJob that walks the graph. A delay node saves a cursor and re-dispatches the job on a delay, so a flow can wait without holding a worker.

Passing data between nodes

Any node's output is available to later nodes by id. Use {{ trigger.x }} for the payload that started the run, and {{ nodeId.field }} for an earlier node's output.

A lone placeholder such as {{ trigger.id }} keeps its original type (int, array, bool). A placeholder inside a longer string is interpolated as text.

Branching

condition() takes a comparison and two closures, one for each branch. The first node added inside a closure is that branch's entry point.

Operators: ==, ===, !=, >, >=, <, <=, in, contains, empty, not_empty.

Triggers

For model triggers, add the TriggersFlowforge trait to the model:

Webhooks can require a shared secret. Pass it to ->webhook('my-secret') and send it as the X-Flowforge-Secret header (or a secret query parameter). A mismatch returns 403.

Built-in nodes

The http_request node also accepts an auth block:

The send_email node sends plain text by default, or HTML when you set html, and accepts cc, bcc, from, and reply_to.

Looping over a list

Inside the loop config, {{ item }} is the current element and {{ index }} is its position. The loop runs in order, in the same process, and collects each run's output under results. For very large lists, fan out with queued jobs instead.

Per-node error handling

Each node config accepts:

• retries: how many extra attempts on failure (defaults to flowforge.node_retries).
• continue_on_error: if true, a failed node is logged and the workflow keeps going instead of stopping.

Custom nodes

This is where Flowforge earns its keep. A node is any class that implements the Node contract. Scaffold one with php artisan make:flowforge-node SlackNode, or write it by hand:

Register it (in a service provider's boot):

Now use it in any workflow:

The engine resolves placeholders in $config before calling handle(), so your node receives plain values. Return NodeResult::ok($output) to continue, NodeResult::branch('true', $output) to branch, or NodeResult::pause($seconds, $output) to wait.

Storing workflows as data

The fluent builder is one way in. You can also store a workflow as an array or JSON and load it from the database. The structure is the same either way: a start node id and a map of nodes, each with type, config, and next (or next_true / next_false for conditions).

Events

The engine fires events you can listen for, so logging, metrics, and alerting stay out of the engine:

• Flowforge\Events\WorkflowStarted (run begins, not on a resume)
• Flowforge\Events\NodeCompleted (each node finishes, success or failure)
• Flowforge\Events\WorkflowCompleted (run finishes successfully)
• Flowforge\Events\WorkflowFailed (a node failed and did not continue on error)

Read-only UI

Flowforge ships an optional read-only UI that lists workflows and shows each run node by node. It is off by default. Turn it on in config/flowforge.php (or set FLOWFORGE_UI_ENABLED=true) and visit /flowforge.

Run logs can hold payloads and email addresses, so the UI is guarded. With no rule set, only the local environment may view it. Define who can see it in production from a service provider's boot:

Reliability

• Validation. Definitions are checked on save: a missing start node, a link to a node that does not exist, an unknown node type, or a cycle is rejected with a clear error instead of failing mid-run.
• Per-node retries. Set retries on a node, or a default with flowforge.node_retries.
• Failed runs. A run that fails records the error and the node it failed at. Resume it from that node with flowforge:retry.
• Stuck runs. If a worker dies hard, the run is swept up by flowforge:reap after flowforge.run_timeout_minutes. Schedule it to run regularly.

Artisan commands

Configuration

config/flowforge.php covers the queue connection and name, the default node retry count, the run timeout used by flowforge:reap, HTTP client timeouts and retries, the webhook route prefix and middleware, and the UI toggle, prefix, and middleware. Every secret comes from the environment. Nothing is hardcoded.

Testing

The package is tested with Orchestra Testbench on an in-memory SQLite database. External calls are faked.

The suite needs the pdo_sqlite extension. CI runs it on PHP 8.2 and 8.3 against Laravel 11 and 12.

Roadmap

• A visual flow editor for the UI (read-only today).
• More built-in nodes (database write, queue fan-out).
• A UI for model-event triggers.
• Sub-workflows (a node that runs another workflow).
• Parallel branches that run concurrently.

License

MIT. See LICENSE.