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.

Basic Usage

Creating a model layer of your application with Smalldb has two steps.

  1. Define database structure.
  2. Define life cycle of each entity.

To define an entity, simply create a JSON file containing all necessary metadata about the entity, like which SQL table it uses and in which file is its state diagram located. That’s all. The moment the JSON file is created your entity is ready for use.

The Smalldb framework then provides an API for each instance of the entity for retrieving its state and modifying it by invoking a transition of the state machine. The API is available as a PHP library and an HTTP interface for AJAX requests.


(CRUD state machine)

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 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 …