Pionia Helpers

Introduction

Pionia exposes global helpers after the application boots (bootstrap/application.php → HTTP or console). They wrap AppRealm, Porm, cache, logging, and Moonlight dispatch.

app() / realm() / container()#

All three return the booted AppRealm singleton (v3):

$debug = app()->environment()->get('DEBUG');
$routes = realm()->getRoutes();
$service = container()->get(MyService::class);

realm() and container() are aliases for the same instance after boot.

db() / table() / connectionManager()#

See Database (Porm). db() is an alias of table().

$row = table('users')->get(1);
$pdo = connectionManager()->connection('default');

cache()#

cache()->set('key', $value, 300);
cache('redis')->get('session:1');

See Caching.

logger() / report()#

logger()->info('Order placed', ['id' => $orderId]);
logger('api')->debug('Payload', $payload);
report($throwable); // exception pipeline logging only

moonlight() / defer() / async()#

Post-response work (same process, not a new thread):

defer(function () {
    logger()->info('Runs after the client received the JSON response');
});

Use defer() for fire-and-forget. Use async(closure) only when you need a promise (.then(), await()). On PHP 8.5+ cast unused promises: (void) async(...).

Moonlight jobs (durable / heavy work):

async('mail', 'send_welcome', ['email' => $user->email]);
moonlight()->async('mail', 'send_welcome', ['email' => $user->email]); // 202 + job_id when RR Jobs enabled
moonlight()->dispatch('auth', 'list_users', ['limit' => 10]);         // sync programmatic call

See Background work for execution order and runtime tables.

API path helpers#

Use these in templates and frontend config — not hard-coded /api/v1 strings.

env() / setEnv() / serverPort()#

$port = serverPort();              // PORT → SERVER_PORT → settings.ini → 8003
$port = serverPort(9001);          // CLI override
setEnv('RUNTIME_FLAG', '1');       // request-scoped

Additional helpers#

alias()#

Resolve a path alias registered on the realm (e.g. PUBLIC_DIR, STORAGE_DIR):

$public = alias(\DIRECTORIES::PUBLIC_DIR->name);

addIniSection()#

Add or update an INI section at runtime (defaults to environment/generated.ini):

addIniSection('plugin_settings', ['foo' => 'bar']);

tap()#

Run a value through a closure and return the original value:

$user = tap($user, fn ($u) => logger()->info('Created', ['id' => $u->id]));

rules()#

Validate multiple fields with pipe-separated rules (same syntax as action attributes):

rules($data, [
    'email' => 'required|email',
    'password' => 'required|password|min:8',
]);

validate()#

Build a field validator from request or service data:

validate('email', $this->request)->required()->email();
validate('phone', $data)->required()->rule('kenya_phone');

validations()#

Shared registry for custom rules (register in a provider or at bootstrap):

validations()->extend('kenya_phone', function (ValidationContext $ctx): void {
    // …
});

See Validations.

envKeys()#

List all .env variable names loaded at boot (used by the developer stats page):

foreach (envKeys() as $name) {
    // ...
}

renderToString() / render()#

Prefer renderToString() for templates — it returns HTML without terminating the process. render() is deprecated and exits in FPM/CLI mode.

$html = renderToString('emails/welcome', ['name' => $user->name]);

cachedResponse() / recached()#

Cache a Moonlight action response when the service has caching enabled:

return cachedResponse($this, response(0, 'OK', $rows), 300);
return recached($this, 0, 'OK', $rows, null, 300);

yesNo() / asBool()#

$label = yesNo($user->active, 'Active', 'Inactive');
if (asBool(env('FEATURE_X'))) { /* ... */ }

router() vs route()#

Use router($app) in provider routes() hooks or advanced boot code. App switches belong in [app_switches] in settings.ini. The route() helper is a deprecated alias.

baseUrl() vs apiBase()#

Prefer apiBase() and the versioned helpers (apiVersionPath(), apiPingPath()) in application code. baseUrl() reads the raw API_BASE environment variable directly.

Framework metadata#

framework(), version(), frameworkLogo(), frameworkTag(), and appName() expose branding from the booted realm. version() returns the installed pionia/pionia-core Composer version (same value shown by php pionia in the CLI banner).

For framework internals (providers, kernel, cache adapters), generate local reference docs with composer document:framework → build/docs/.