05_callbacks.php

<?php
declare(strict_types=1);

/**
 * Example 05 — Instance Callbacks (CallbackInterface)
 *
 * Objects can implement CallbackInterface (via CallbackTrait) to register
 * their own callbacks. The executor picks these up automatically:
 *
 *   ON_BEFORE -> PRE callbacks -> ON_MID -> POST callbacks -> ON_AFTER
 *
 * CallbackEntry wraps each callback with:
 *   - event name (which event it applies to)
 *   - stage(s)   ("pre", "post", or both)
 *   - priority   (higher runs first, default 2)
 */

require __DIR__ . '/../vendor/autoload.php';

use Minfra\Chains\EventExecutor;
use Minfra\Chains\EventInterface;
use Minfra\Chains\CallbackInterface;
use Minfra\Chains\CallbackTrait;
use Minfra\Chains\CallbackEntry;
use Minfra\Chains\BasicResultInterface;
use Minfra\Chains\Result;
use Minfra\Chains\Meta;

echo "=== 05: Instance Callbacks ===\n\n";

// ---- 5a. Basic PRE and POST callbacks ----

$obj = new class implements CallbackInterface {
    use CallbackTrait;
    public array $log = [];

    function __construct() {
        $this->appendCallback(
            (new CallbackEntry('save', 'pre'))
                ->setCallback(function (Meta $d) {
                    $d->this->log[] = 'PRE:validate';
                    return true;
                }),
            (new CallbackEntry('save', 'post'))
                ->setCallback(function (Meta $d) {
                    $d->this->log[] = 'POST:notify';
                    return Result::true($d, completed: true);
                }),
        );
    }
};

$result = EventExecutor::run(
    instance: $obj,
    name: 'save',
    hooks: [
        EventInterface::ON_MID => function (Meta $d) {
            $d->this->log[] = 'HOOK:persist';
            return null;
        },
    ],
);

echo "5a) Execution order: " . implode(' -> ', $obj->log) . "\n\n";

// ---- 5b. Priority — higher priority runs first ----

$obj = new class implements CallbackInterface {
    use CallbackTrait;
    public array $log = [];

    function __construct() {
        $this->appendCallback(
            (new CallbackEntry('process', 'pre', priority: 1))
                ->setCallback(function (Meta $d) {
                    $d->this->log[] = 'low(1)';
                    return true;
                }),
            (new CallbackEntry('process', 'pre', priority: 10))
                ->setCallback(function (Meta $d) {
                    $d->this->log[] = 'high(10)';
                    return true;
                }),
            (new CallbackEntry('process', 'pre', priority: 5))
                ->setCallback(function (Meta $d) {
                    $d->this->log[] = 'mid(5)';
                    return true;
                }),
        );
    }
};

EventExecutor::run(instance: $obj, name: 'process');

echo "5b) Priority order: " . implode(' -> ', $obj->log) . "  (10 first)\n\n";

// ---- 5c. null stage = both PRE and POST ----

$obj = new class implements CallbackInterface {
    use CallbackTrait;
    public array $log = [];

    function __construct() {
        $this->appendCallback(
            (new CallbackEntry('run', null))    // null = both PRE and POST
                ->setCallback(function (Meta $d, string $phase) {
                    $d->this->log[] = $phase;
                    return true;
                }),
        );
    }
};

EventExecutor::run(instance: $obj, name: 'run');

echo "5c) null stage -> ran in: " . implode(', ', $obj->log) . "\n\n";

// ---- 5d. Callbacks only trigger for their registered event name ----

$obj = new class implements CallbackInterface {
    use CallbackTrait;
    public array $log = [];

    function __construct() {
        $this->appendCallback(
            (new CallbackEntry('save', 'pre'))
                ->setCallback(function (Meta $d) {
                    $d->this->log[] = 'save-callback';
                    return true;
                }),
            (new CallbackEntry('delete', 'pre'))
                ->setCallback(function (Meta $d) {
                    $d->this->log[] = 'delete-callback';
                    return true;
                }),
        );
    }
};

EventExecutor::run(instance: $obj, name: 'save');
echo "5d) Event 'save'   triggered: " . implode(', ', $obj->log) . "\n";

$obj->log = [];
EventExecutor::run(instance: $obj, name: 'delete');
echo "    Event 'delete' triggered: " . implode(', ', $obj->log) . "\n\n";

// ---- 5e. prependCallback vs appendCallback ----

$obj = new class implements CallbackInterface {
    use CallbackTrait;
    public array $log = [];
};

$obj->appendCallback(
    (new CallbackEntry('run', 'pre', priority: 2))
        ->setCallback(function (Meta $d) { $d->this->log[] = 'appended'; return true; }),
);

$obj->prependCallback(
    (new CallbackEntry('run', 'pre', priority: 2))
        ->setCallback(function (Meta $d) { $d->this->log[] = 'prepended'; return true; }),
);

EventExecutor::run(instance: $obj, name: 'run');
echo "5e) Same priority, prepend wins: " . implode(' -> ', $obj->log) . "\n";

echo "\n--- 05 done ---\n";