PHPackages                             token27/nexus-ai-workflows - 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. token27/nexus-ai-workflows

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

token27/nexus-ai-workflows
==========================

AI-native workflow engine with graph orchestration, resumable execution, nodes, guards, middleware, persistence, and observability.

v1.0.0(2mo ago)0191MITPHP ^8.3

Since May 22Compare

[ Source](https://github.com/token27/nexus-ai-workflows)[ Packagist](https://packagist.org/packages/token27/nexus-ai-workflows)[ Docs](https://github.com/token27/nexus-ai-workflows)[ RSS](/packages/token27-nexus-ai-workflows/feed)WikiDiscussions Synced 3w ago

READMEChangelog (1)Dependencies (8)Versions (2)Used By (1)

NexusAI Workflows
=================

[](#nexusai-workflows)

[![CI](https://github.com/token27/nexus-ai-workflows/actions/workflows/ci.yml/badge.svg)](https://github.com/token27/nexus-ai-workflows/actions)[![Latest Version](https://camo.githubusercontent.com/aa6297e4fc9018f455a2df8da34e78438a00b87e074c354a8e9129fc4b562102/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746f6b656e32372f6e657875732d61692d776f726b666c6f77732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/token27/nexus-ai-workflows)[![PHP 8.3+](https://camo.githubusercontent.com/38027453aeb7eb818641c9de8f82b7624c3558d92634f1946edc715c3ddf8956/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332532422d3737374242343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://php.net)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](LICENSE)

A graph-based workflow orchestration engine for PHP 8.3+. Define directed workflow graphs of nodes: AI calls, tool executions, conditionals, loops, parallel branches, waits, and sub-workflows. Run them with middleware, guards, persistence stores, resumable execution, and observability.

Built on top of [NexusAI](https://github.com/token27/nexus-ai) for seamless LLM integration.

Features
--------

[](#features)

- **Fluent WorkflowBuilder**: declarative, chainable API for constructing workflow graphs
- **8 node types**: ActionNode, AINode, ToolNode, ConditionNode, LoopNode, ParallelNode, WaitNode, SubWorkflowNode
- **WorkflowRunner**: executes graphs following transitions until completion, failure, or suspension
- **Resumable execution**: WaitNode suspends a workflow and `resume()` continues from the suspended node without re-running previous steps
- **Transition guards**: ExpressionGuard closures and AIGuard LLM-based decisions
- **Middleware pipeline**: onion architecture for cross-cutting concerns per step
- **Persistence stores**: FileWorkflowStore, CacheWorkflowStore, and InMemoryWorkflowStore for workflow snapshots
- **Observability**: EventBus integration with typed workflow event DTOs
- **FakeWorkflowRunner**: testing without HTTP calls, with assertion helpers
- **Immutable context**: thread-safe WorkflowContext that flows through nodes

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

[](#installation)

```
composer require token27/nexus-ai-workflows
```

Requires [nexus-ai](https://github.com/token27/nexus-ai) as a dependency:

```
composer require token27/nexus-ai guzzlehttp/guzzle
```

Quick Start
-----------

[](#quick-start)

```
use Token27\NexusAI\Driver\DriverRegistry;
use Token27\NexusAI\Workflows\Engine\WorkflowBuilder;
use Token27\NexusAI\Workflows\Engine\WorkflowContext;
use Token27\NexusAI\Workflows\Runner\WorkflowRunner;

// 1. Register your LLM drivers.
$registry = new DriverRegistry();
$registry->register('openai', fn () => /* your OpenAI driver */);

// 2. Build a workflow.
$workflow = WorkflowBuilder::named('research-pipeline')
    ->addAINode('analyze', 'openai', 'gpt-4o', 'Analyze this topic: {{_input}}')
    ->addActionNode('format', fn ($ctx) => $ctx->with('output', strtoupper($ctx->get('output'))))
    ->addTransition('analyze', 'format')
    ->build();

// 3. Run it.
$runner = new WorkflowRunner($registry);
$result = $runner->run($workflow, WorkflowContext::from(['_input' => 'PHP async']));

echo $result->output['output'];
echo $result->elapsedMs;
```

Examples
--------

[](#examples)

Runnable examples are available in [`examples/`](examples/):

- [`01-basic-action-workflow.php`](examples/01-basic-action-workflow.php): pure PHP workflow without AI calls
- [`02-fake-ai-workflow.php`](examples/02-fake-ai-workflow.php): test an AI workflow with `FakeWorkflowRunner`
- [`03-suspend-resume-tasks.php`](examples/03-suspend-resume-tasks.php): CakePHP-style multi-task suspend/resume flow
- [`04-branch-loop-workflow.php`](examples/04-branch-loop-workflow.php): branching and loops

Run one locally after `composer install`:

```
php examples/03-suspend-resume-tasks.php
```

Documentation
-------------

[](#documentation)

Full documentation is available in the [`docs/`](docs/) directory:

- [Getting Started](docs/getting-started.md)
- [WorkflowBuilder](docs/workflow-builder.md)
- [Node Types](docs/node-types.md)
- [Transitions & Guards](docs/transitions-and-guards.md)
- [WorkflowRunner](docs/workflow-runner.md)
- [Context & State](docs/context-and-state.md)
- [Persistence](docs/persistence.md)
- [Observability](docs/observability.md)
- [Testing](docs/testing.md)

Architecture
------------

[](#architecture)

```
WorkflowBuilder::named('my-flow')     addAINode(...)                  addTransition(...)              build()