Pionia Helpers

Who this is for#

You are writing DeskFlow services and want quick access to common framework entry points — response() for Moonlight envelopes, table() for tasks / team_members, logger() for action traces — without wiring the container manually.

What you will learn#

• Which helpers to use for Moonlight responses, Porm queries, and logging
• Boot constraints (AppRealm::create() before helpers work)
• Where to find security, cache, async, and validation shortcuts

Before you start#

How it works#

Pionia exposes global helpers after the application boots. They wrap AppRealm, Porm, cache, logging, and Moonlight dispatch.

DeskFlow Moonlight responses — response()#

Return the standard JSON envelope from any service action:

protected function listAction(Arrayable $data): ApiResponse
{
    $rows = table('tasks')->where('status', $data->get('status', 'open'))->all();

    return response(0, 'OK', ['tasks' => $rows]);
}

protected function createAction(Arrayable $data): ApiResponse
{
    $this->mustAuthenticate();

    return response(0, 'Task created', ['id' => $newId]);
}

Related response helpers:

$html = renderToString('emails/welcome', ['name' => $member->name]);
return cachedResponse($this, response(0, 'OK', $rows), 300);

Prefer renderToString() over deprecated render() (which exits in FPM/CLI).

DeskFlow data access — table() / db()#

Query Northwind tables through Porm:

$task = table('tasks')->get($id);
$members = table('team_members')->where('active', 1)->all();
$pdo = connectionManager()->connection('default');

See Database (Porm).

DeskFlow observability — logger() / report()#

Trace actions and report throwables through the exception pipeline:

protected function updateAction(Arrayable $data): ApiResponse
{
    logger()->info('task.update', [
        'task_id' => $data->get('id'),
        'user' => $this->auth()?->user?->email,
    ]);

    try {
        // …
    } catch (\Throwable $e) {
        report($e);
        throw $e;
    }

    return response(0, 'Updated');
}

logger('api')->debug('Payload', $payload);

See Logging.

Application access — 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.

Moonlight dispatch — 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('member', 'list', ['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. Prefer them over deprecated route() or raw baseUrl() in application code.

Environment and runtime — env() / serverPort()#

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

Security — security() and secure_*#

security() returns the Pionia\Security\Security singleton. Every method has a snake_case helper.

Full reference: Security utilities.

$token = secure_token();
$hash = hash_password($plain);
$sealed = encrypt_with_public_key('payload', $publicKey);

Validation — rules() / validate() / validations()#

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

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

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

See Validations.

Caching — cache()#

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

See Caching.

Other helpers#

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

Common mistakes#

• Calling table() or logger() inside bootstrap/application.php before AppRealm::create() returns
• Using render() in tests or workers — prefer renderToString() to avoid unexpected process exit
• Hard-coding /api/v1 instead of apiVersionPath() — breaks when adding v2
• Using deprecated route() instead of router($app) in providers

What’s next#