README

A PHP library for building event-driven execution chains with hooks, callbacks, policies, and a rich result system. Zero dependencies.

Chains lets you wrap any operation in a structured pipeline of phases and hooks, so that internal and external code can intercept, validate, transform, or react to every step — without tight coupling.

Current library focuses on reusability. You can implement once and customize the class behavior on according to the business needs.

Requirements

PHP 8.2+

Installation

composer require minfra/chains

Quick Start

use Minfra\Chains\EventExecutor;
use Minfra\Chains\EventInterface;
use Minfra\Chains\Result;
use Minfra\Chains\Meta;
use Minfra\Chains\BasicResultInterface;

//A simple example with real world application.
class Product {
    protected string $price;
    
    function setPrice(string $price): BasicResultInterface {
        return EventExecutor::run($this, 'set_price', Meta::make(price: $price), [
        EventInterface::ON_MID => [$this, '_set_price'], // or a single hook (any callable)
]);
    }
    
    protected function _set_price(Meta $meta): void {
        $meta->this->price = $meta->price;  // $meta->this refers to the current object.
        // We could also do `return true;` or do `Result::true($meta)` or `Result::true()` or `Result::true(<ANYTHING>)`
        
        // when returning true or returning null(or no return at all). it automatically passes the $meta to the next phase.
    }
}

// The above example, but even simpler
class Product {
    protected string $price;
    
    function setPrice(string $price): BasicResultInterface {
        return EventExecutor::run($this, 'set_price', ...CommonEvents::setter(['price' => $price]));  // CommonEvents provides wheels for working with properties
    }
}

// The same as above example, but with more hooks[pipeline]
class Product {
    protected string $price;
    
    function setPrice(string $price): BasicResultInterface {
        list($meta, $setter_cb) = CommonEvents::setter(['price' => $price]);
        
        return EventExecutor::run($this, 'set_price', $meta, [
            EventInterface::ON_BEFORE => [[$this, "_ensure_correct_price"], [$this, "_ensure_correct_decimal_price"]],
            EventInterface::ON_MID    => [[$this, "_set_price"]],
            EventInterface::ON_OK     => fn(Meta $meta) => error_log("price is: {$meta->price}"),
        ]);
    }
    
    protected function _ensure_correct_price(Meta $meta): BasicResultInterface|true {
        if (!is_numeric($meta->price)) {
            return Result::false("invalid_price", $meta);  // Or simply: Result::false("invalid_price");
        }
        
        return true;  // when returning true. it automatically passes the $meta to the next phase.
    }
    
    protected function _ensure_correct_decimal_price(Meta $meta): void {
        $meta->price = bcmath($meta->price, '1', 2);
    }
    
    protected function _set_price(Meta $meta): void {
        $meta->this->price = $meta->price;  // $meta->this refers to the current object.
        // We could also do `return true;` or do `Result::true($meta)` or `Result::true()` or `Result::true(<ANYTHING>)`
        
        // when returning null(or no return at all). it automatically passes the $meta to the next phase.
    }
}

// The same as above example, but make it pluggable(register external callbacks)
use Minfra\Chains\EventExecutor;
use Minfra\Chains\EventInterface;
use Minfra\Chains\CallbackTrait;
use Minfra\Chains\CommonEvents;
use Minfra\Chains\Result;
use Minfra\Chains\BasicResultInterface;
use Minfra\Chains\Meta;

class Product implements \Minfra\Chains\CallbackInterface {
    use CallbackTrait;

    protected string $price;
    protected int $type;

    const EVENT_ON_SET_TYPE = "set_type";
    const EVENT_ON_GET_TYPE = "get_type";

    const EVENT_ON_SET_PRICE = "set_price";
    const EVENT_ON_GET_PRICE = "get_price";

    function setType(int $type): BasicResultInterface {
        return EventExecutor::run($this, static::EVENT_ON_SET_TYPE, ...CommonEvents::setter(['type' => $type]));
    }

    function getType(): Result {
        $type = $this->type ?? null;
        return EventExecutor::run($this, static::EVENT_ON_GET_TYPE, ...CommonEvents::getter('type', $type));
    }

    function setPrice(string $price): BasicResultInterface {
        list($meta, $setter_cb) = CommonEvents::setter(['price' => $price]);

        return EventExecutor::run($this, static::EVENT_ON_SET_PRICE, $meta, [
            EventInterface::ON_BEFORE => [[$this, "_ensure_correct_price"], [$this, "_ensure_correct_decimal_price"]],
            EventInterface::ON_MID    => [$setter_cb],
            EventInterface::ON_OK     => fn(Meta $meta) => error_log("price is: {$meta->price}"),
        ]);
    }

    function getPrice(): Result {
        $price = $this->price ?? null;
        return EventExecutor::run($this, static::EVENT_ON_GET_PRICE, ...CommonEvents::getter('price', $price));
    }

    protected function _ensure_correct_price(Meta $meta): BasicResultInterface|true {
        if (!is_numeric($meta->price)) {
            return Result::false("invalid_price", $meta);  // Or simply: Result::false("invalid_price");
        }

        return true;  // when returning true. it automatically passes the $meta to the next phase.
    }

    protected function _ensure_correct_decimal_price(Meta $meta): BasicResultInterface|true {
        // $meta->price = bcmath($meta->price, '1', 2);
        return true;
    }
}

$product = new Product();
$product->appendCallback((new \Minfra\Chains\CallbackEntry($product::EVENT_ON_SET_PRICE, \Minfra\Chains\CallbackEntryInterface::EVENT_PRE))->setCallback(function(Meta $meta) {
    /** @var Product $product */
    $product = $meta->this;
    if ($product->getType()->data()->type === 222) {
        if ($meta->price > "20") {
            return Result::false("invalid_product_222_issue", ['reason' => 'cannot be higher than 20']);
            // or if you prefer using meta: return Result::false("invalid_product_222_issue", Meta::make(reason: 'cannot be higher than 20'));
        }
    }

    return true;
}));
$product->appendCallback((new \Minfra\Chains\CallbackEntry($product::EVENT_ON_SET_PRICE, \Minfra\Chains\CallbackEntryInterface::EVENT_POST))->setCallback(function(Meta $meta) {
    var_dump("I got the price: {$meta->price}. let's do something with it.");
}));


$product->setType(222);
var_dump($product->setPrice('21')->ok()); // false
var_dump($product->setPrice('19')->ok()); // true

You can run the latest example here

How It Works

Every call to EventExecutor::run() executes a fixed sequence of phases:

ON_BEFORE → PRE callbacks → ON_MID → POST callbacks → ON_AFTER
                                                          │
                         ┌────────────────────────────────┘
                         ▼
              ON_INCOMPLETE  (if not completed)
              ON_DONE        (if done flag set)
              ON_OK          (if ok)
              ON_FAILED      (if not ok)

Hooks are functions, methods or closures you pass to EventExecutor::run(), keyed by phase.
Callbacks are externally registered on the instance itself (via CallbackInterface) and run at the PRE and POST stages. think of them as plugin.
Results flow through the chain. Each step can inspect, modify, or replace the current result.
Policies control what happens on failure, incomplete results, retries, and early termination.

Key Concepts

Result

The value object that flows through the chain. Carries state flags and a data payload.

Result::true($data, completed: true);          // success
Result::false('error_code', $data);            // failure
Result::incomplete('pending', $data);          // not yet done
Result::from($otherResult, ok: false);         // clone with overrides

$result->ok();         // bool — success?
$result->data();       // mixed — the payload
$result->status();     // string — error/status code
$result->completed();  // bool — work fully done?
$result->done();       // bool — stop the chain early?
$result->again();      // bool — retry this step?

Callback Return Contract

Every hook/callback receives ($data, $phase, $executor, $result) and returns:

Return value	Effect
`null` or `true`	Continue with the current result unchanged
`BasicResultInterface`	Replace the current result

CommonEvents Helpers

Ready-made [Meta, callable] pairs for property operations on objects — including protected/private properties. Use the spread operator to pass them to EventExecutor::run():

// Set protected properties
EventExecutor::run($obj, 'set_name', ...CommonEvents::setter(['name' => 'Alice']));

// Read & validate
EventExecutor::run($obj, 'get_name', ...CommonEvents::getter('name', $value));

// Array operations
EventExecutor::run($obj, 'add_tag',  ...CommonEvents::adding('tags', ['php']));
EventExecutor::run($obj, 'append',   ...CommonEvents::append('logs', 'auth', ['entry']));

// Remove & reset
EventExecutor::run($obj, 'remove',   ...CommonEvents::removing(['email']));
EventExecutor::run($obj, 'clear',    ...CommonEvents::cleanup('tags', []));

CallbackInterface

Objects that implement CallbackInterface (via CallbackTrait) can register their own callbacks. The executor picks them up automatically:

class Order implements CallbackInterface {
    use CallbackTrait;

    function __construct() {
        $this->appendCallback(
            (new CallbackEntry('save', 'pre'))
                ->setCallback(function (Meta $d) {
                    // validate before save
                    return true;
                }),
            (new CallbackEntry('save', 'post'))
                ->setCallback(function (Meta $d) {
                    // notify after save
                    return Result::true($d, completed: true);
                }),
        );
    }
}

Execution Policy

DefaultEventExecutorPolicy controls chain behavior:

$policy = new DefaultEventExecutorPolicy(
    jump_on_failure: true,            // continue chain after a failed step
    jump_on_incomplete: false,        // stop on incomplete results
    keep_running_on_done: false,      // stop when done flag is set
    ignore_failed_data_on_jump: true, // don't forward failed data
    mark_incomplete_as_failed: true,  // treat incomplete as failure
    again_limit: 1,                   // max retries per callback
);

EventExecutor::run($instance, 'event', policy: $policy, ...);

Source Interfaces

An instance can implement these optional interfaces so the executor automatically queries it for configuration — no extra arguments needed:

Interface	Method	Purpose
`EventSourceDataInterface`	`getEventData($name, $data)`	Provide custom event data
`EventSourceHooksInterface`	`getEventHooks($name, $hooks)`	Inject hooks automatically
`EventSourcePolicyInterface`	`getEventExecutorPolicy($name)`	Provide per-event policy

Retry Mechanism

A callback can request a retry by calling setAgain() on the result. The executor triggers ON_AGAIN, then re-runs the callback up to againLimit times:

function (Meta $d) {
    if ($transientFailure) {
        return Result::true($d)->setAgain();
    }
    return Result::true($d, completed: true);
}

Examples

The examples/ directory contains runnable scripts covering every feature:

File	Topic
`01_minimal.php`	Simplest possible usage
`02_hooks_and_phases.php`	Full phase lifecycle, terminal hooks
`03_results.php`	Result creation, states, `from()`
`04_common_events.php`	getter/setter/adding/removing/cleanup, safe reflection
`05_callbacks.php`	CallbackInterface, PRE/POST stages, priority
`06_policy.php`	All policy options demonstrated
`07_retry.php`	again mechanism, limits, abort
`08_source_interfaces.php`	EventSourceData/Hooks/Policy interfaces
`09_model_lifecycle.php`	Full domain model with event-driven getters/setters

# Run all examples
php examples/run_all.php

# Run a single example
php examples/01_minimal.php

Tutorial

See TUTORIAL.md for a step-by-step walkthrough from basic usage to building a full domain model with event-driven property access.

minfrastructure / chains

Maintainers

Package info

Statistics

Security