Smalldb, the state machine abstraction layer, is the framework to build a model layer of your application using state machines. Smalldb combines formal finite automata, simple PHP code and powerful SQL database into a single elegant package.


(CRUD state machine)


Smalldb framework is currently under heavy development as it is transitioning from a research prototype (libSmalldb versions up to 0.8) into a production-ready framework (the upcomming version 2.0). Some of the features above are available in older versions only, and they are being refactored and updated right now.


Smalldb uses PHPUnit to run tests. The tests produce HTML output to demonstrate various features like running the STS Algorithm on BPMN diagrams.

State Machine Definition Example

The state machine in the diagram above can be defined using the following class:

 * @StateMachine("crud-item")
abstract class Item extends ItemDataImmutable implements ReferenceInterface
     * @State(color = "#def")
    const EXISTS = "Exists";

     * @Transition("", {"Exists"}, color = "#4a0")
    abstract public function modify(ItemDataImmutable $data);

     * @Transition("Exists", {"Exists"})
    abstract public function update(ItemDataImmutable $data);

     * @Transition("Exists", {""}, color = "#a40")
    abstract public function delete();

The complex state machines may load diagrams from additional files instead:

 * @StateMachine("pizza-delivery")
 * @IncludeBPMN("PizzaDelivery.bpmn",
 *         targetParticipant="Participant_StateMachine",
 *         svgFileName="PizzaDelivery.svg")
abstract class PizzaDelivery implements ReferenceInterface
     * @Transition
    abstract public function create(string $pizzaType);

    // ... We only declare the transitions and their parameters.

Note that the use of annotations is available in the upcomming version 2.0 only (the master branch). The older versions (up to 0.8) use JSON configuration files instead; however, the semantics is the same.

Basic concept

Each entity in Smalldb is represented using a state machine, which describes behavior and life cycle of the entity. A simple CRUD entity is modeled using a simple state machine with three transitions to create, modify and delete an instance of the entity (see the diagram above). More complex entities can be easily implemented using more states and transitions to express what actions can entity perform at which moments of its life cycle.

Unlike traditional finite automata implementations, where each state machine instance exists as instantiated object, Smalldb state machines are considered abstract entities which exist outside the application with an independent life cycle. Smalldb framework then provides an API to communicate with the state machine instances, instead of representing them.

Smalldb is designed (but not limited) to run on top of a SQL database, where each row in a designated SQL table represents a single instance of a given Smalldb state machine. Transitions of the state machine, implemented as PHP methods, then perform SQL queries to modify data in the database.

Smalldb expects nothing more than a good database design and does not limit you from using the full power of SQL, yet it does not bother you with simple repetitive queries.

Why state machines?

Understandability. State machines provide an elegant way to specify a behavior of an entity in an understandable way. They are often used during software development process (see UML state machine). In contrast to a source code, a state machine diagram is understandable to non-technical people (with some explanation), so it is possible to discuss business logic effectively with customers or put new programmers on the track quickly.

Visualization. The primary way of defining a state machine is a state diagram. What else to say? Smalldb framework provides tools to both render a state machine diagram using Grafovatko or Graphviz and to import the diagram you drew (and saved as a GraphML file) to use it directly as part of an application source code (no coding involved). One way or another, there is always an up-to-date diagram you can include in your documentation, show in an administration interface or put on your wall.

Simple API. Read state, invoke transition. — That is the API of Smalldb state machine. Then there is a listing API to browse existing state machine instances (a simple facade for a configurable SQL query builder) and a reflection API to get the state machine definition. That’s it.

Formal background. Finite automata (on which Smalldb stands) is a simple formal concept. It is relatively easy to prove formally many interesting properties of given finite automata, like state reachability and liveness to make sure your users won’t get stuck somewhere, even when they have only limited permissions. The formally verified software is no longer matter of academic discussion, Smalldb brings it to real-world applications.

See also:


All these examples were rendered automatically by libSmalldb (and using Graphviz).

A blog post in CMS. Write it and publish it. Or delete it. (blogpost diagram)

An article, which can be accepted or rejected by an editor. Like the previous blog post example, but with some review workflow. (article diagram)

Bug in a bug tracking system: Bug is created when a user reports it, then it may be assigned to a programmer or directly resolved. If everything is good, it will get closed, and if not, it can be reopened. (bug diagram)

A taxi order. Customer calls a taxi, taxi waits for customer and taximeter updates price of the order. Then customer rides to his destination and finally pays the ride. (taxi order diagram)

See also …