09_model_lifecycle.php

<?php
declare(strict_types=1);

/**
 * Example 09 — Real-World Pattern: Domain Model with Event-Driven Lifecycle
 *
 * This example shows the intended usage pattern: a domain model whose
 * getters and setters go through event chains, allowing external code to
 * hook into every property change and read.
 *
 * This is the same pattern used in production (e.g. finance library) where
 * traits like StatusTrait, CostTrait, NamedTrait wrap every property
 * access in EventExecutor::run() + CommonEvents helpers.
 */

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

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

echo "=== 09: Domain Model Lifecycle ===\n\n";

$b = fn(bool $v) => $v ? 'true' : 'false';

// ---------------------------------------------------------------------------
// Define event name constants (like interfaces do in a real project)
// ---------------------------------------------------------------------------
const EVENT_SET_NAME   = 'on_set_name';
const EVENT_GET_NAME   = 'on_get_name';
const EVENT_SET_PRICE  = 'on_set_price';
const EVENT_GET_PRICE  = 'on_get_price';
const EVENT_SET_STATUS = 'on_set_status';
const EVENT_GET_STATUS = 'on_get_status';

// ---------------------------------------------------------------------------
// The domain model — uses CommonEvents for getter/setter patterns
// ---------------------------------------------------------------------------

class Product implements CallbackInterface, EventSourceHooksInterface {
    use CallbackTrait;

    protected string $name = '';
    protected float $price = 0.0;
    protected string $status = 'draft';

    function __construct() {
        // Register a PRE callback that validates price on every set_price event
        $this->appendCallback(
            (new CallbackEntry(EVENT_SET_PRICE, 'pre'))
                ->setCallback(function (Meta $d) {
                    if ($d->price < 0) {
                        return Result::false('price_cannot_be_negative', $d);
                    }
                    return true;
                }),
        );

        // Register a POST callback that auto-activates when price is set above 0
        $this->appendCallback(
            (new CallbackEntry(EVENT_SET_PRICE, 'post'))
                ->setCallback(function (Meta $d) {
                    if ($d->price > 0 && CommonEvents::safeAttributeGet($d->this, 'status') === 'draft') {
                        CommonEvents::safeAttributeSet($d->this, 'status', 'active');
                    }
                    return true;
                }),
        );
    }

    // -- Event source: auto-inject hooks for all events --
    function getEventHooks(string $name, array $hooks): array {
        // Automatically add an audit log to ON_AFTER for every setter
        if (str_starts_with($name, 'on_set_')) {
            $hooks[EventInterface::ON_AFTER][] = function (Meta $d) use ($name) {
                echo "    [audit] {$name} completed\n";
                return null;
            };
        }
        return $hooks;
    }

    // -- Getters / Setters via event chains --

    function setName(string $name): BasicResultInterface {
        return EventExecutor::run($this, EVENT_SET_NAME, ...CommonEvents::setter(['name' => $name]));
    }

    function getName(): BasicResultInterface {
        return EventExecutor::run($this, EVENT_GET_NAME, ...CommonEvents::getter('name', $this->name ?? null));
    }

    function setPrice(float $price): BasicResultInterface {
        return EventExecutor::run($this, EVENT_SET_PRICE, ...CommonEvents::setter(['price' => $price]));
    }

    function getPrice(): BasicResultInterface {
        return EventExecutor::run($this, EVENT_GET_PRICE, ...CommonEvents::getter('price', $this->price ?? null));
    }

    function setStatus(string $status): BasicResultInterface {
        return EventExecutor::run($this, EVENT_SET_STATUS, ...CommonEvents::setter(['status' => $status]));
    }

    function getStatus(): BasicResultInterface {
        return EventExecutor::run($this, EVENT_GET_STATUS, ...CommonEvents::getter('status', $this->status ?? null));
    }
}

// ---------------------------------------------------------------------------
// Usage
// ---------------------------------------------------------------------------

$product = new Product();

// Set name
echo "9a) Set name:\n";
$r = $product->setName('Widget');
echo "    ok={$b($r->ok())}\n";
echo "    name={$product->getName()->data()->name}\n\n";

// Set price (valid)
echo "9b) Set price = 29.99:\n";
$r = $product->setPrice(29.99);
echo "    ok={$b($r->ok())}\n";
echo "    price={$product->getPrice()->data()->price}\n";
echo "    status={$product->getStatus()->data()->status}  (auto-activated from draft)\n\n";

// Set price (invalid — negative)
echo "9c) Set price = -5 (should fail):\n";
$r = $product->setPrice(-5);
echo "    ok={$b($r->ok())}, status={$r->status()}\n";
echo "    price={$product->getPrice()->data()->price}  (unchanged)\n\n";

// ---------------------------------------------------------------------------
// External hook — a consumer adds validation without modifying Product
// ---------------------------------------------------------------------------

echo "9d) External hooks from outside the class:\n";

$product2 = new Product();

// Add an external PRE callback that enforces max price
$product2->appendCallback(
    (new CallbackEntry(EVENT_SET_PRICE, 'pre', priority: 10))
        ->setCallback(function (Meta $d) {
            if ($d->price > 1000) {
                return Result::false('price_exceeds_max', $d);
            }
            return true;
        }),
);

$r = $product2->setPrice(500);
echo "    price=500 -> ok={$b($r->ok())}\n";

$r = $product2->setPrice(1500);
echo "    price=1500 -> ok={$b($r->ok())}, status={$r->status()}\n\n";

// ---------------------------------------------------------------------------
// Using the done flag for early termination from hooks
// ---------------------------------------------------------------------------

echo "9e) ON_BEFORE hook with early termination (done):\n";

$result = EventExecutor::run(
    instance: $product,
    name: EVENT_SET_STATUS,
    data: Meta::make(status: 'archived', params: ['status']),
    hooks: [
        EventInterface::ON_BEFORE => function (Meta $d) {
            // Don't allow changing status of active products to archived
            if (CommonEvents::safeAttributeGet($d->this, 'status') === 'active') {
                echo "    [guard] Cannot archive active product\n";
                return Result::true($d, completed: true)->setDone();
            }
            return null;
        },
    ],
);

echo "    status={$product->getStatus()->data()->status}  (unchanged, hook terminated early)\n";

echo "\n--- 09 done ---\n";