Agent

Agent

The Agent object is injected into your controller's __onInit() and __onLoad() hooks. Use it to register routes, events, API commands, bridge commands, and configure module behaviour.

Route Registration

addRoute(mixed $route, $path = null): static

Register a URL route pattern mapped to a controller closure file. The framework matches the URL left-to-right against registered patterns.

Pattern Syntax

| Token | Matches | Example |

| --- | --- | --- |

| :d | Digits only | /user/:d → /user/42 |

| :a | Any non-slash characters | /post/:a → /post/abc-123 |

| :w | Word characters (a-zA-Z, 0-9, _) | /tag/:w → /tag/my_tag |

| :W | Non-word characters | /sep/:W → /sep/--.. |

| :D | Non-digit characters | /code/:D → /code/abc |

| :[regex] | Custom character class | :[a-z0-9-] → custom match |

| {min,max} | Length constraint | :a{3,50} → 3-50 non-slash characters |

// Single route

$agent->addRoute('/', 'index');

$agent->addRoute('/user/:d', 'showUser');

$agent->addRoute('/post/:a{3,50}', 'showPost');



// Array syntax for multiple routes

$agent->addRoute([

    '/'           => 'index',

    '/create'     => 'createForm',

    '/edit/:d'    => 'editForm',

    '/file/:*'    => 'serveFile',

]);

📝 Note: Closure files: The $path maps to a PHP file in controller/. E.g. 'showUser' → controller/{module_code}.showUser.php.

addLazyRoute(mixed $route, mixed $path = null): static

Register a lazily-resolved route. The handler file is only loaded when the route is actually matched.

Supports nested arrays to define hierarchical routes where each level corresponds to a URL path segment and folder level. Use @self as a key to map the current directory level itself.

HTTP method prefixes (e.g. POST, GET|POST) can appear at any nesting level. A method on a parent key is inherited by all children unless overridden:

// Flat registration

$agent->addLazyRoute('GET /users', 'list');



// Nested — all children inherit POST

$agent->addLazyRoute(['POST api' => [

    'fetch'  => 'fetch',   // POST api/fetch

    'add'    => 'add',     // POST api/add

]]);



// Nested — per-leaf methods

$agent->addLazyRoute(['api' => [

    'fetch'       => 'fetch',   // Any method

    'POST add'    => 'add',     // POST only

    'POST delete' => 'delete',  // POST only

]]);



// Override inherited method

$agent->addLazyRoute(['GET api' => [

    'list'        => 'list',    // GET (inherited)

    'POST create' => 'create',  // POST (overridden)

]]);

💡 Tip: Use for: Large modules with many routes where loading all handlers upfront would hurt startup performance.

addShadowRoute(string $route, string $moduleCode, string $path = ''): static

Redirect a matched route to another module's handler. The URL stays the same but processing is delegated.

// Delegate /admin routes to admin_panel module

$agent->addShadowRoute('/admin', 'admin_panel', 'dashboard');

addScript($route, $path = null): self

Add a script-mode route. Scripts execute after normal routing and can produce additional output (e.g. analytics, footers).

Event Listening

listen(mixed $event, null|string|callable $path = null): bool|array

Register event listener(s). When another module fires the event via trigger(), your callback runs.

// Single event

$agent->listen('user.login', 'handleUserLogin');



// Multiple events

$agent->listen([

    'user.login'  => 'handleLogin',

    'user.logout' => 'handleLogout',

    'order.placed' => 'handleOrder',

]);

API & Bridge

addAPICommand(mixed $command, ?string $path = null): static

Register a command that other modules can call via $this->api('your_module')->commandName().

$agent->addAPICommand('getUser', 'apiGetUser');

$agent->addAPICommand('validateEmail', 'apiValidateEmail');



// Array syntax

$agent->addAPICommand([

    'getUser'       => 'apiGetUser',

    'updateProfile' => 'apiUpdateProfile',

]);

addBridgeCommand(mixed $command, ?string $path = null): static

Register commands for cross-distributor (cross-domain) communication via the internal bridge.

Module Interaction

await(string $moduleCode, callable $caller): static

Register a callback to execute when a specific module becomes ready. Useful when your module depends on another module's initialization.

$agent->await('auth_module', function(ModuleInfo $authInfo) {

    // auth_module is now ready, safe to use its API

});

thread(): ThreadManager

Get the module's ThreadManager for spawning background processes. See Thread & ThreadManager.

← PreviousController

Next → Routing