PHPackages                             maduser/argon-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. maduser/argon-workflows

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

maduser/argon-workflows
=======================

A PHP package for managing workflows

v1.0.2(1mo ago)02[1 issues](https://github.com/judus/argon-workflows/issues)MITPHPPHP >=8.2CI passing

Since Jul 24Pushed 1mo agoCompare

[ Source](https://github.com/judus/argon-workflows)[ Packagist](https://packagist.org/packages/maduser/argon-workflows)[ RSS](/packages/maduser-argon-workflows/feed)WikiDiscussions main Synced today

READMEChangelog (3)Dependencies (13)Versions (7)Used By (0)

[![PHP](https://camo.githubusercontent.com/ce3e396e4f1bbbd326f628872a1414656d28065f2712cda0868d8eff07320aec/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e322b2d626c7565)](https://www.php.net/)[![Build](https://github.com/judus/argon-workflows/actions/workflows/php.yml/badge.svg)](https://github.com/judus/argon-workflows/actions)[![codecov](https://camo.githubusercontent.com/0fe71f3849f2a725af6d781ac164989231e396673d93a0fe1845509317e76f5d/68747470733a2f2f636f6465636f762e696f2f67682f6a756475732f6172676f6e2d776f726b666c6f77732f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/judus/argon-workflows)[![Psalm Level](https://camo.githubusercontent.com/f9064b1393226e50541559975394be2006e7ae46d8a138717c0c62378988835b/68747470733a2f2f73686570686572642e6465762f6769746875622f6a756475732f6172676f6e2d776f726b666c6f77732f636f7665726167652e737667)](https://shepherd.dev/github/judus/argon-workflows)[![Latest Version](https://camo.githubusercontent.com/c1aac452871d3e9e0c594a1abec01ce808fa760c94b936e3b3bc928c2eecaf7f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6164757365722f6172676f6e2d776f726b666c6f77732e737667)](https://packagist.org/packages/maduser/argon-workflows)[![Downloads](https://camo.githubusercontent.com/6258c7e33ddba236159a8c9f3ec078c18f7057fa5d63ffb290c737d7bffd0199/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6164757365722f6172676f6e2d776f726b666c6f77732e737667)](https://packagist.org/packages/maduser/argon-workflows)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)

Argon Workflows
===============

[](#argon-workflows)

A minimal workflow runner. Define state handlers and wire them together into workflows. Transitions can be static or triggered by signals emitted from handlers.

Basic Concept
-------------

[](#basic-concept)

Define a `ContextInterface` that represents the state of your system and passes through your workflow.

Each state has a `StateHandlerInterface`, which processes the context and returns a `HandlerResult`, possibly with transition signals.

The `WorkflowRunner` coordinates:

- Calling handlers in a loop
- Transitioning based on signal or static mapping
- Emitting execution events for logging, telemetry, queue correlation, or UI updates

The runner has a configurable max-step guard. This prevents broken workflow definitions from looping forever.

Example
-------

[](#example)

```
$context = new MyContext(state: 'start');

$registry = new StateHandlerRegistry();
$registry->register('start', new StartHandler());
$registry->register('next', new NextHandler());

$workflow = new WorkflowDefinition(
    staticTransitions: ['start' => 'next'],
    signalTransitions: ['done' => 'final']
);

$workflows = new WorkflowRegistry();
$workflows->add('default', $workflow);

$runner = new WorkflowRunner(
    $registry,
    new TransitionResolver(),
    $workflows,
    maxSteps: 1000
);

$finalContext = $runner->run($context);
```

Execution Events
----------------

[](#execution-events)

The runner can emit execution events for run, step, and transition lifecycle changes. Provide your own `runId` when you want to correlate runs with external systems.

```
$observer = new MyExecutionObserver();
$runner = new WorkflowRunner(
    $registry,
    new TransitionResolver(),
    $workflows,
    null,
    $observer
);

$finalContext = $runner->run($context, 'default', runId: 'job-123');
```

Transition Behavior
-------------------

[](#transition-behavior)

If a handler emits a signal through `HandlerResult::$signals`, that takes precedence over the static transition.

```
return new HandlerResult(
    context: $context,
    signals: ['done' => true]
);
```

If no signals match, the runner falls back to the static transition based on the current state.

Signal transitions are global in the current model:

- The first truthy matching signal wins.
- Signal transitions are not scoped to the current state.
- Use distinct signal names when the same signal would mean different targets in different states.

Graph Export
------------

[](#graph-export)

You can export a workflow definition as a graph to visualize it in a UI.

```
$graph = $workflow->toGraph();
```

Signal transitions use `from = '*'` in the exported graph because they are global.

Integration Example
-------------------

[](#integration-example)

In a real project:

```
final class Agent
{
    public function __construct(
        private WorkflowRunner $workflowRunner,
    ) {}

    public function run(string $agentId, string $input): LLMResponse
    {
        $context = new AgentContext(agentId: $agentId, input: $input);
        $result = $this->workflowRunner->run($context, 'default', runId: $context->agentId);

        return $result->getFinalResponse()
            ?? throw new RuntimeException('Agent completed but returned no response.');
    }
}
```

Interface Definitions
---------------------

[](#interface-definitions)

Implement:

- `ContextInterface`: your workflow data object. The runner expects `withState()` to return a context of the same concrete type.
- `StateHandlerInterface`: logic per step/state.

Boundaries
----------

[](#boundaries)

This package does not provide persistence, queue execution, scheduling, retries, locking, or dependency injection integration.

Observers fail the workflow if they throw. Wrap observers yourself if telemetry failures should be swallowed.

Handlers are registered directly in `StateHandlerRegistry`. Container-backed handler resolution belongs in an integration layer, not in the workflow runner core.

License
-------

[](#license)

MIT License

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance92

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity53

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 ~152 days

Total

3

Last Release

40d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7fb9da5a15010d335622bf9f465a32ef79c8d1cffcd139c2a9114736b72e2c13?d=identicon)[jdu](/maintainers/jdu)

---

Top Contributors

[![judus](https://avatars.githubusercontent.com/u/1478654?v=4)](https://github.com/judus "judus (24 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/maduser-argon-workflows/health.svg)

```
[![Health](https://phpackages.com/badges/maduser-argon-workflows/health.svg)](https://phpackages.com/packages/maduser-argon-workflows)
```

###  Alternatives

[presseddigital/linkit

One link field to rule them all.

28165.7k](/packages/presseddigital-linkit)

PHPackages © 2026

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