PHPackages                             pwm/s-flow - 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. pwm/s-flow

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

pwm/s-flow
==========

A lightweight library for defining state machines

4.0.1(7y ago)742.5k1MITPHPPHP >=7.2.0

Since May 18Pushed 7y ago2 watchersCompare

[ Source](https://github.com/pwm/s-flow)[ Packagist](https://packagist.org/packages/pwm/s-flow)[ Docs](https://github.com/pwm/s-flow)[ RSS](/packages/pwm-s-flow/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (5)Versions (7)Used By (0)

S-Flow
======

[](#s-flow)

[![Build Status](https://camo.githubusercontent.com/48f5a2c3fb9072f59edb908af0eefafae4cf34081610b039c9bb21bc09d160f1/68747470733a2f2f7472617669732d63692e6f72672f70776d2f732d666c6f772e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/pwm/s-flow)[![codecov](https://camo.githubusercontent.com/d075feea40cac14aa53fd8b6c1613d8be1b4fe2d295da0244a1165e5eb56010a/68747470733a2f2f636f6465636f762e696f2f67682f70776d2f732d666c6f772f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/pwm/s-flow)[![Maintainability](https://camo.githubusercontent.com/d4d6fed7cbd2372301f2243db362af0435e34822c5e314646d9e18707586775c/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f37643638643862656532656362636633323737632f6d61696e7461696e6162696c697479)](https://codeclimate.com/github/pwm/s-flow/maintainability)[![Test Coverage](https://camo.githubusercontent.com/bb0c1c8ed5a3bf7046cd9eaa0f099b09ea705319d2deb7ef9ce4c46c501a7c65/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f37643638643862656532656362636633323737632f746573745f636f766572616765)](https://codeclimate.com/github/pwm/s-flow/test_coverage)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)

S-Flow is a lightweight library for defining finite state machines (FSM). Once defined the machine can be run by giving it a start state and a sequence of events to derive some end state. One of the main design goals of S-Flow was to be able to define FSMs declaratively as a single top level definition. This makes the structure of the underlying graph clear and explicit which in turn helps with understanding and maintenance. S-Flow can be used for many things, eg. to define workflows or to build event sourced systems.

Table of Contents
-----------------

[](#table-of-contents)

- [Why](#why)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [How it works](#how-it-works)
- [Tests](#tests)
- [Todo](#todo)
- [Changelog](#changelog)
- [Licence](#licence)

Why
---

[](#why)

If you ever named a variable, object property or database field *"status"* or *"state"* then read on...

#### Claim #1:

[](#claim-1)

Much grief in software development arises from our inability to control state.

#### Evidence:

[](#evidence)

Q: What do we do when our code breaks?

A: We debug it.

Q: What does debugging mean?

A: Observing our program's internal state trying to figure out where it went wrong.

#### Claim #2:

[](#claim-2)

If we could better control state in our programs we would have less bugs and as a result we would spend less time debugging.

S-Flow can help controlling state by making it easy to build state machines.

Requirements
------------

[](#requirements)

PHP 7.2+

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

[](#installation)

```
$ composer require pwm/s-flow

```

Usage
-----

[](#usage)

There is a fully worked example under [tests/unit/ShoppingCart](tests/unit/ShoppingCart) that simulates the process of purchasing items from an imaginary shop. Below is the definition of the FSM from it:

```
// S, E and T are short for State, Event and Transition

// A list of state names that identify the states
$stateNames = [
    S\NoItems::name(),
    S\HasItems::name(),
    S\NoCard::name(),
    S\CardSelected::name(),
    S\CardConfirmed::name(),
    S\OrderPlaced::name(),
];

// A list of arrows labelled by event names
// An arrow goes from a start state via a transition to an end state
$arrows = [
    (new Arrow(E\Select::name()))->from(S\NoItems::name())->via(new T\AddFirstItem),
    (new Arrow(E\Select::name()))->from(S\HasItems::name())->via(new T\AddItem),
    (new Arrow(E\Checkout::name()))->from(S\HasItems::name())->via(new T\DoCheckout),
    (new Arrow(E\SelectCard::name()))->from(S\NoCard::name())->via(new T\DoSelectCard),
    (new Arrow(E\Confirm::name()))->from(S\CardSelected::name())->via(new T\ConfirmCard),
    (new Arrow(E\PlaceOrder::name()))->from(S\CardConfirmed::name())->via(new T\DoPlaceOrder),
    (new Arrow(E\Cancel::name()))->from(S\NoCard::name())->via(new T\DoCancel),
    (new Arrow(E\Cancel::name()))->from(S\CardSelected::name())->via(new T\DoCancel),
    (new Arrow(E\Cancel::name()))->from(S\CardConfirmed::name())->via(new T\DoCancel),
];

// Build a graph from the above
$graph = (new Graph(...$stateNames))->drawArrows(...$arrows);

// Build an FSM using the graph
$shoppingCartFSM = new FSM($graph);

// Run a simulation of purchasing 3 items
$result = $shoppingCartFSM->run(
    new S\NoItems,
    new Events(
        new E\Select(new Item('foo')),
        new E\Select(new Item('bar')),
        new E\Select(new Item('baz')),
        new E\Checkout,
        new E\SelectCard(new Card('Visa', '1234567812345678')),
        new E\Confirm,
        new E\PlaceOrder
    )
);

// Observe the results
assert($result->isSuccess() === true);
assert($result->getState() instanceof S\OrderPlaced);
assert($result->getLastEvent() instanceof E\PlaceOrder);
```

How it works
------------

[](#how-it-works)

A state machine is defined as a directed graph. Vertices of this graph are called states and arrows between them are called transitions. Transitions are labelled so that they can be identified. We call those labels events.

Running the machine, ie. deriving an end state given a start state and a sequence of events, means walking the graph from the start state via a sequence of transitions leading to the desired end state. In the end we either reach it or stop when there is no way forward.

Transitions, acting as the arrows of the graph, are functions of type `(State, Event) -> State`. They are uniquely identified by a `(StateName, EventName)` pair, ie. given a state name and an event name (which is the label of the arrow) we can get the corresponding transition function, if it exists. The the absence of the transition function automatically results in a failed transition, keeping the current state.

Success and failure is captured using the `TransitionOp` type. It also keeps track of the current state as well as the sequence of events leading up to it.

Tests
-----

[](#tests)

```
$ composer phpunit
$ composer phpcs
$ composer phpstan
$ composer psalm
$ composer infection

```

Todo
----

[](#todo)

Once return type covariance lands in PHP ([as part of this RFC](https://wiki.php.net/rfc/covariant-returns-and-contravariant-parameters)) we will be able to specify the actual return type of `__invoke` in `Transition` implementations. This would enable to easily dump the FSM into various text formats, eg. as a DOT file, etc...

Changelog
---------

[](#changelog)

[Click here](changelog.md)

Licence
-------

[](#licence)

[MIT](LICENSE)

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity28

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity62

Established project with proven stability

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

Recently: every ~73 days

Total

6

Last Release

2665d ago

Major Versions

1.0.0 → 2.0.02018-05-24

2.1.0 → 3.0.02018-09-28

3.0.0 → 4.0.02019-03-12

PHP version history (2 changes)1.0.0PHP >=7.1.0

4.0.0PHP >=7.2.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/195513?v=4)[Zsolt Szende](/maintainers/pwm)[@pwm](https://github.com/pwm)

---

Top Contributors

[![pwm](https://avatars.githubusercontent.com/u/195513?v=4)](https://github.com/pwm "pwm (28 commits)")

---

Tags

event-sourcingfsmstate-machineworkflowworkflowevent sourcingfsmstate-machine

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Psalm

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/pwm-s-flow/health.svg)

```
[![Health](https://phpackages.com/badges/pwm-s-flow/health.svg)](https://phpackages.com/packages/pwm-s-flow)
```

###  Alternatives

[ecotone/ecotone

Enterprise architecture layer for Laravel and Symfony — CQRS, Event Sourcing, Durable Workflows (Sagas, Orchestrators), Projections, and Outbox messaging via PHP attributes.

562565.8k42](/packages/ecotone-ecotone)[tarfin-labs/event-machine

Event-driven state machines for Laravel with event sourcing, type-safe context, and full audit trail.

199.1k](/packages/tarfin-labs-event-machine)[shrink0r/workflux

Finite state machine for php.

375.6k1](/packages/shrink0r-workflux)[piece/stagehand-fsm

A finite state machine

3666.2k3](/packages/piece-stagehand-fsm)[ringierimu/state-workflow

Laravel State Workflow provide tools for defining and managing workflows and activities with ease.

3264.7k](/packages/ringierimu-state-workflow)[phpmentors/stagehand-fsm

A finite state machine

361.1k](/packages/phpmentors-stagehand-fsm)

PHPackages © 2026

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