README

Framework-agnostic orchestration engine for single-active finite state machines in PHP.

What It Does

Activates one automaton at a time and drives it through discrete tick() cycles
Wraps each cycle with optional middleware
Dispatches commands and events through a lightweight in-memory message bus
Emits lifecycle events for activation and applied transitions
Supports snapshot/restore for shared context and serializable automata state

What It Does Not Do

No statechart semantics
No parallel or multi-active automata runtime
No built-in persistence transport or async messaging backend

Start Here

Build your first automaton: docs/getting-started.md
Understand orchestrator semantics: docs/orchestrator.md, docs/commands-events.md, docs/snapshots.md
Browse extension and reference docs: docs/context.md, docs/extending.md, docs/testing.md

The full documentation hub lives at docs/index.md.

Requirements

PHP 8.1 or newer
Composer

Installation

composer require chatflowphp/automata

Quick Start

<?php

use Automata\Contracts\AutomatonInterface;
use Automata\Contracts\ContextInterface;
use Automata\Contracts\InputInterface;
use Automata\Core\Context\ArrayContext;
use Automata\Core\CycleRequest;
use Automata\Core\CycleResponse;
use Automata\Core\Orchestrator;

$context = new ArrayContext();

$automaton = new class implements AutomatonInterface {
    public function getId(): string
    {
        return 'demo';
    }

    public function onEnter(ContextInterface $context): void
    {
        $context->set('status', 'idle');
    }

    public function process(CycleRequest $request): CycleResponse
    {
        $request->getContext()->set('status', 'processed');

        return CycleResponse::none();
    }

    public function onLeave(ContextInterface $context): void
    {
    }
};

$orchestrator = new Orchestrator($context);
$orchestrator->registerAutomaton($automaton);
$orchestrator->activate('demo');
$orchestrator->tick(new class implements InputInterface {});

For the guided beginner path, use docs/getting-started.md and the runnable simple-workflow example.

Reading Order

Examples

Simple Workflow

simple-workflow is the shortest runnable example:

php examples/simple-workflow/run.php

It demonstrates:

Orchestrator
ArrayContext
two automata
middleware
one transition command
one domain event
one listener
snapshot and restore

Traffic Light

traffic-light is the advanced canonical demo:

php examples/traffic-light/run.php

It demonstrates:

three automata connected by transitions
middleware-driven tick counting
domain events observed after transitions
lifecycle events
snapshot save, restore, and resumed execution

Read examples/traffic-light/README.md after the beginner path.

Testing

composer test

Full local quality gate:

composer check

License

This project is released under the MIT License. See LICENSE for details.

chatflowphp / automata

Maintainers

Package info

Statistics

Security