divengine / runner
Lightweight PHP engine for Sequential Flow Model (SFM) flows: shared context, YAML flows compiled to PHP, calls, jumps and pause/resume.
Requires
- php: ^8.1
Requires (Dev)
- phpbench/phpbench: ^1.3
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^10.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-21 01:21:26 UTC
README
Divengine Runner is a lightweight PHP engine that executes flows of the
Sequential Flow Model (SFM):
ordered blocks of steps that share one mutable context array, with explicit
call, jump and pause transitions.
It follows the Divengine philosophy: one source file (src/runner.php), one
class (divengine\runner\runner), no runtime dependencies and a small static API.
A separate entry file, bin/run.php, runs flows from the terminal through that
API.
What it is
- An execution engine for PHP callables and YAML flow definitions, used from
PHP code or from the terminal (
php vendor/divengine/runner/bin/run.php). - A YAML-to-PHP compiler: a YAML flow becomes a real PHP closure you can run or save.
- A PHP implementation of the SFM execution semantics of the Python reference runtime (see SFM compatibility).
What it is not
- Not a job queue, scheduler or persistence layer: storing a paused context and running it again is up to you.
- Not a visual modeler, validator or simulator.
- Not a sandbox: flows, activities and conditions are trusted PHP code (see Security).
Requirements and installation
PHP 8.1 or newer (tested on 8.1–8.5). No PHP extensions beyond the default ones.
composer require divengine/runner
Callable flows
A flow is any callable whose first parameter is array &$context:
use divengine\runner\runner; $context = ["name" => "World"]; runner::run(function (array &$context): void { $context["greeting"] = "Hello " . $context["name"]; }, $context); echo $context["greeting"]; // Hello World echo $context["_runner_state"]; // done
runner::run() also accepts a path to a PHP file that returns such a callable.
YAML flows
# flows/order.yml id: order blocks: main: steps: total: activity: compute_total # functions/compute_total.php review: call: review.check # run review from step check, then come back receipt: activity: format_receipt review: steps: check: condition: needs_review # false skips the rest of the step context: reviewed: true pause: true
Each activity and condition is a PHP file that returns a callable:
<?php // functions/compute_total.php return function (array &$context): float { $total = 0.0; foreach ($context["items"] as $item) { $total += $item["price"] * $item["qty"]; } return $total; // stored as $context["total"] (the step id) };
<?php // functions/needs_review.php return fn (array &$context): bool => $context["total"] >= 20 && empty($context["reviewed"]);
<?php // functions/format_receipt.php return fn (array &$context): string => sprintf("Total: %.2f%s", $context["total"], empty($context["reviewed"]) ? "" : " (reviewed)");
Run it, pause, and resume with the same context:
use divengine\runner\runner; $context = [ "items" => [["price" => 10, "qty" => 2], ["price" => 5, "qty" => 1]], "_root_folder" => __DIR__ . "/functions", ]; runner::run(__DIR__ . "/flows/order.yml", $context); echo $context["_runner_state"], PHP_EOL; // paused runner::run(__DIR__ . "/flows/order.yml", $context); echo $context["_runner_state"], PHP_EOL; // done echo $context["receipt"], PHP_EOL; // Total: 25.00 (reviewed)
Expected output:
paused
done
Total: 25.00 (reviewed)
This example lives in examples/order and runs in CI.
Step semantics
A step may combine these keys; they run in this order:
condition: callable; a false result skips the rest of the step.context: mapping merged into the context.call:block.step; runs the target block from that step, then returns into this step.activity: callable; its return value is stored in$context[<step id>].jump:block.step; transfers control without returning.pause:true; stops the run so it can be resumed after this step.
module (optional) names the module that the step's condition and activity
belong to (see Function resolution).
blocks and steps are mappings keyed by id, in execution order; the first
block is the entry. Blocks do not fall through: the flow ends when the running
block finishes. block. targets step 0 of a block and .step the current block. Block and step
ids must not start with _ (reserved keys) or contain .. Unknown keys and
wrongly typed values are rejected when the flow is compiled. Conditions use PHP
truthiness, so return booleans.
Compile to PHP
$code = runner::generateFlowCodeFromYaml("flows/order.yml"); // PHP source (deterministic) file_put_contents("order_flow.php", "<?php\n" . $code); // a regular flow file $flow = runner::flowFromYaml("flows/order.yml"); // callable closure runner::runYaml("flows/order.yml", $context); // compile and run
Option function_map renames activity and condition references at compile
time. Keys and values are qualified names, module:name or a plain name:
["billing:total" => "billing_v2:total", "total" => "billing:total"].
Function resolution
The root folder is _root_folder from the context (read at each import), else
DIV_RUNNER_ROOT_FOLDER (default ./). The .php extension is optional and a
file must return a callable.
Without module, a name resolves to the first match of:
<root>/<name>.php;<name>.phpas a path (absolute or relative to the working directory);- a callable name such as
strlenorvendor\package\fn(e.g. Composer-autoloaded).
With module, a name resolves only inside the module folder:
_modules[<module>] from the context when set, else <root>/<module>. Nothing
outside that folder is tried, so the same function name in two modules never
collides:
steps: invoice_total: module: billing # <root>/billing/total.php activity: total shipping_total: module: shipping # <root>/shipping/total.php activity: total rounded: activity: round_total # <root>/round_total.php, a path or a callable
$context["_modules"] = ["shipping" => "/srv/app/vendor-flows/shipping"]; // optional override
Module names use letters, digits, _ and -; inside a module, a function name
is relative (total, rates/total) without . or .. segments. Both are
checked at compile time. Activities import other functions with
$context["_importer"]("total", "shipping") (module optional).
A missing function fails the run with Function import failed: <module>:<name>
(or <name>) and an error log entry.
Command line
The package ships a small PHP entry file that runs one flow with
runner::run(). PHP itself is the executable; there is nothing else to
install or build:
php vendor/divengine/runner/bin/run.php flows/order.yml --root functions php vendor/divengine/runner/bin/run.php flows/order.yml --context input.json --root functions php vendor/divengine/runner/bin/run.php flows/order.yml --context state.json --save-context state.json
| Option | Meaning |
|---|---|
<flow> |
A .yml, .yaml or .php flow file. |
--context <file> |
Initial context: a JSON object. |
--root <dir> |
Folder of activity and condition files; sets _root_folder. |
--save-context <file> |
Write the resulting context as JSON. The file is replaced atomically (temporary file in the same folder, then rename). |
--json |
Print the resulting context as JSON instead of the state. |
-h, --help |
Usage. |
Relative paths are relative to the current working directory, so run it from
your project folder. This also applies to relative _root_folder and _modules
values inside the context file. Without --root or _root_folder, functions
resolve from the working directory, as with the PHP API.
Output and exit codes. stdout carries only the result: one line with the
final state, or the context as JSON with --json. Diagnostics go to stderr, and
so does anything the flow prints, including PHP warnings, so the JSON on stdout
stays intact.
| Exit code | stdout | Meaning |
|---|---|---|
0 |
done |
The flow finished. |
3 |
paused |
The flow paused; resume it with the saved context. |
1 |
error |
The flow ended in the error state: a failing step, or a setup error such as invalid YAML. The message is on stderr. |
2 |
(empty) | Invocation error. Either the arguments are bad or an input is missing or unreadable, and the flow did not run. Or the context could not be saved or printed as JSON (see below); then stderr says how the flow ended and which value failed, and an existing --save-context file is left unchanged. |
Pause and resume across processes. Save the context of the first run and pass the same file back. Each run is a new PHP process, and steps that already ran are not repeated:
$ php vendor/divengine/runner/bin/run.php flows/order.yml --context input.json --root functions --save-context state.json paused $ echo $? 3 $ php vendor/divengine/runner/bin/run.php flows/order.yml --context state.json --save-context state.json done $ php -r 'echo json_decode(file_get_contents("state.json"), true)["receipt"], PHP_EOL;' Total: 25.00 (reviewed)
Before --save-context or --json writes anything, the context is checked to
contain only values that come back unchanged from JSON: null, booleans,
integers, floats, strings and arrays of them, at most 512 levels deep. Objects
(closures included) and resources are rejected, even nested inside arrays,
because json_encode() would turn them into plain JSON objects or fail. The same
happens with values that json_encode() cannot encode, such as NAN or invalid
UTF-8. One remaining limitation: an empty JSON object {} comes back as an
empty array [].
--root is stored in the context as an absolute path, so the resume run does not
need it again. On an error, Runner clears the resume state as it does with the
API (see Pause and resume), and the saved context then
starts at the first block on the next run.
In a shell script, test for the codes explicitly:
php vendor/divengine/runner/bin/run.php flows/order.yml --context state.json --save-context state.json case $? in 0) echo "done" ;; 3) echo "paused, run again later" ;; *) echo "failed" >&2; exit 1 ;; esac
The entry file loads your project's Composer autoloader, so flows can use your classes and Composer-autoloaded functions. It does nothing else: no framework bootstrap, scheduler, queue or worker. Flows, activities and conditions are trusted PHP code; the command line does not sandbox them (see Security).
Optional project shortcut. PHP does not install a run command. If you want
php run flows/order.yml, add this file named run to your project root:
<?php require __DIR__ . "/vendor/divengine/runner/bin/run.php";
php run flows/order.yml --root functions
Context contract
All callables receive the same array &$context. Keys starting with _ or __
are reserved; the runner writes _runner_state (processing, done, paused,
error), _runner_result, _runner_error, _runner_logs, _runner_started_at
and _runner_ended_at. The full list is in docs/context-keys.md.
Errors raised by a flow are caught and recorded (_runner_state = error).
Setup errors (unreadable or invalid YAML, unresolved flow, wrong signature) are
thrown to the caller and also recorded in the context.
Pause and resume
pause: true, or an activity that throws an exception whose message contains$context["_exception_pause"], pauses the run at that step.- Resume by calling
runner::run()again with the stored context, in the same or another process: execution continues after the paused step. - Pauses work at any depth of
call: the return frames of every pending call are kept in_flow_stack, so after a pause in C (called from B, called from A) the resumed run finishes C, returns into B's calling step, then into A's. Steps that already ran are not repeated. _autoresume: truemakes the runner resume immediately once.
Called blocks and nested flows pause differently. A block reached through
call is part of the same flow: a pause inside it pauses the whole run, and the
resumed run continues through every pending caller. A flow used as an
activity is a separate invocation with its own control scope: a pause inside it
ends that child invocation early, its activity result is null, and the parent
flow continues without pausing. The child is not resumed later.
After an error, _runner_state is error, _runner_error and
_runner_result describe it, and the resume state is cleared (_flow_state
and _flow_stack become []). Your business data stays as the flow left it,
and the next run starts at the first block. This holds for errors inside steps,
inside called blocks and before a saved position was reached (for example a
resumed flow whose paused block no longer exists), and for setup errors that
run() throws.
When runner::run() returns, the runner has removed its own runtime helpers
and block callables from the context. What remains is your data, the
_runner_* metadata and the resume state (_flow_state, _flow_stack). The
runner's part is plain arrays and scalars; whether the whole context can be
stored with json_encode() depends on the values your code put in it, which
Runner does not check or convert. With data-only values it round-trips through
json_decode($json, true):
file_put_contents("job.json", json_encode($context, JSON_THROW_ON_ERROR)); // later, in any process: $context = json_decode(file_get_contents("job.json"), true, 512, JSON_THROW_ON_ERROR); runner::run("flows/order.yml", $context);
Limitations: JSON serialization of user-supplied values is not guaranteed
(closures, objects, resources, non-UTF-8 strings and floats such as NAN are
yours to remove or re-provide when you resume from storage); a resumed run does
not re-apply your initial context for you; jump loops are not limited (recursive calls and nested flows are, by _max_call_depth, default 256).
Public API
| Method | Purpose |
|---|---|
runner::run($flow, &$context, $options) |
Run a callable, a PHP flow file or a YAML flow. Options: logger, shared_context, function_map, require_context_param_name. |
runner::runYaml($path, &$context, $options) |
Compile and run a YAML flow. |
runner::flowFromYaml($path, $options) |
Compile a YAML flow to a closure. |
runner::generateFlowCodeFromYaml($path, $options) |
Compile a YAML flow to PHP source. |
runner::importer($name, $module, $context, $logger) |
Resolve a function as described above. |
runner::setLogger($logger) |
Global log sink. |
runner::safeSerialize($data), runner::dumpException($e) |
Diagnostic helpers. |
The other public static methods (flowLoop, checkPause, updateContext,
resumeAfterCall, wrapCondition, wrapActivity, wrapCall, wrapJump,
wrapPause) are called by generated flow code and are marked @internal.
Logging
runner::setLogger(function (string $level, string $message, array $context = []): void { error_log("[$level] $message"); }); // or per run: runner::run($flow, $context, ["logger" => $callable]);
Logs of each run are also stored in $context["_runner_logs"].
Documentation
- docs/README.md: overview and YAML API
- docs/sfm-compatibility.md: SFM compatibility matrix
- docs/security.md: trust boundary
- docs/context-keys.md: reserved context keys
- docs/book/: book chapters (
composer docs:pdfbuilds a PDF)
Development
composer install composer test # PHPUnit composer phpstan # static analysis composer smoke # install the dist archive in a clean project and run the example composer bench # phpbench baseline
Releases are created by pushing a vX.Y.Z tag on main; see releases/README.md.
License
GPL-3.0-or-later. See LICENSE.
Powered by Divengine Software Solutions