Relayer

Opinionated, batteries-included framework on top of polidog/use-php. Bundles:

A Next.js App Router-style file-based router (src/Pages/page.psx, layout.psx, dynamic segments, error pages)
File-based JSON API routes (src/Pages/.../route.php) — a method-keyed map of autowired handlers, each returning a Response (Response::json() / text() / noContent() / redirect()); OPTIONS / HEAD synthesized like Next.js Route Handlers
Per-page / per-layout external scripts ($ctx->js() / PageComponent::addJs() / LayoutComponent::addJs()) emitted at the end of <body> after the bundle, in declaration order
React islands (Island::mount()) — a rich-UI escape hatch: server-rendered shell, client React component, props from PHP, your own bundle
Optional root middleware (src/Pages/middleware.php) wrapping every dispatch, plus a ready-made Cors middleware
CSRF-protected server actions ($ctx->action() / PageComponent::action() dispatch form posts to in-page handlers)
Symfony DependencyInjection for service wiring (autowire, YAML/PHP config auto-load)
symfony/dotenv for .env loading with the standard .env / .env.local / .env.{APP_ENV} cascade
#[Cache] attribute for HTTP cache headers + If-None-Match 304 handling with pluggable EtagStore (file-based default, Redis-ready)
Session-based authentication: #[Auth] attribute / $ctx->requireAuth(), role checks, password hashing, pluggable UserProvider and SessionStorage
Bearer token auth: server-side Firebase / Cognito ID-token verification (JWKS, cached + rotation-aware) — stateless API or verify-then-session, same #[Auth] guard
Zod-style schema validation (Validator::object(), safeParse / parse, form-input coercion + per-field errors)
A dev-only request profiler (/_profiler view, no-op in production)

Exposes a single Relayer::boot() entrypoint so app code stays small.

Requirements

Installation

composer require polidog/relayer

Scaffold a new project

relayer init lays the project structure into the current directory. Run it from your project root after requiring the framework:

composer require polidog/relayer
vendor/bin/relayer init
composer install
php -S 127.0.0.1:8000 -t public

composer install (rather than dump-autoload) so the App\ autoload and the publish scripts init just added both apply — the latter emits public/usephp.js, which the default document references.

It is idempotent and non-destructive:

existing files are never overwritten (they are reported as skipped), so it is safe to re-run;
your existing composer.json is patched additively — it adds the App\ PSR-4 autoload, the usePHP asset-publish scripts, and an extra.relayer.structure_version marker, and leaves everything else untouched.

The structure_version marker records which skeleton shape the project was generated against, so relayer upgrade (below) can migrate it forward.

init also scaffolds RELAYER.md — concise, authoritative coding conventions for agents/LLMs working in the project (file conventions, the route.php / middleware.php / Island contracts, the minimal-design philosophy, a "do not" list) — plus 2-line AGENTS.md and CLAUDE.md pointers to it (the filenames agent tools / Claude Code auto-read). All ship inside polidog/relayer, so they are co-versioned with the framework and cannot drift, and all are skip-if-exists, so a project's own AGENTS.md / CLAUDE.md is never overwritten. It additionally scaffolds Claude Code tooling under .claude/ — a relayer-routing skill (the routing / Response / CSRF contracts, trigger-scoped) and a relayer-reviewer subagent that reviews changes against RELAYER.md. Both defer to RELAYER.md as the single source of truth and are co-versioned + skip-if-exists for the same reason. Run vendor/bin/relayer routes for the project's actual route map.

Upgrading the project structure

When you bump polidog/relayer, newer framework versions may add files to the generated skeleton. relayer upgrade brings an existing project up to the installed framework's structure:

composer update polidog/relayer
vendor/bin/relayer upgrade
composer install

It reads the extra.relayer.structure_version marker, writes only the files added in the versions between it and the current one, then advances the marker (the one mutation init deliberately never makes). Every step is skip-if-exists, so files you have edited are kept and reported as skipped; the scope is exactly the structure deltas plus the marker — it does not touch composer scripts or autoload (re-run relayer init for those — it is additive and safe). It is idempotent: once at the current version it reports nothing to do. If the project has no marker it was not created by relayer init; run init first to stamp the current shape.

Project Layout

your-app/
  .env                 # loaded automatically if present
  composer.json
  config/
    services.yaml      # auto-loaded if present (also services.php / .yml)
  public/
    index.php
  src/
    Pages/             # AppRouter file-based routes live here
      layout.psx
      page.psx
      about/
        page.psx
    AppConfigurator.php # your service registrations (extends Polidog\Relayer\AppConfigurator)

Quick Start

public/index.php:

<?php
declare(strict_types=1);

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

use Polidog\Relayer\Relayer;

Relayer::boot(__DIR__ . '/..')->run();

That's the whole entrypoint. boot() will:

Load .env from the project root (if present) into $_ENV / $_SERVER.
Build a Symfony ContainerBuilder, auto-load config/services.{yaml,yml,php} if present, then let AppConfigurator register services on it.
Compile the container and wrap it in a PSR-11 adapter for AppRouter.
Enable autoCompilePsx automatically when APP_ENV=dev.

The returned AppRouter is fully configured. You can still customize before running:

$router = Relayer::boot(__DIR__ . '/..');
$router->setJsPath('/assets/app.js');
$router->addCssPath('/assets/style.css');
$router->run();

Environment Variables

Put a .env in the project root:

APP_ENV=dev
DATABASE_DSN=mysql:host=127.0.0.1;dbname=app;charset=utf8mb4
DATABASE_USER=app
DATABASE_PASSWORD=secret

# i18n (all optional — see Internationalization)
APP_LOCALE=en
APP_LOCALES=en,ja
LOCALE_COOKIE=locale
LOCALE_PATH_PREFIX=true

DATABASE_* is optional — the database layer is wired only when DATABASE_DSN is set (see Database). APP_LOCALE / APP_LOCALES / LOCALE_COOKIE / LOCALE_PATH_PREFIX are optional too — an app that sets none stays single-locale English at no cost (see Internationalization).

.env files are loaded through symfony/dotenv with the standard Symfony cascade:

.env — committed defaults
.env.local — local overrides (gitignored)
.env.{APP_ENV} — per-environment defaults (committed)
.env.{APP_ENV}.local — per-environment local overrides (gitignored)

Missing files are skipped silently. Variables already in $_ENV / $_SERVER / getenv() win over the base .env; the .local files override the committed counterparts.

APP_ENV=dev (or development) enables PSX auto-compilation. Any other value (including unset) treats the app as production: pre-compile with vendor/bin/usephp compile src/Pages during deploy.

Routing & Pages

The router scans src/Pages/ and maps the filesystem to URLs in the spirit of the Next.js App Router. The conventions:

File	Role
`page.psx`	Renders the route. One per directory.
`layout.psx`	Wraps every nested page; layouts stack from root to leaf.
`error.psx`	Error page for 404 / `$ctx->abort()` statuses (root only).
`route.php`	JSON API route (no HTML). Method-keyed handler map. One per directory.
`[param]/`	Dynamic segment; captured into `$this->getParam('param')`.
`(group)/`	Route group: organises files without adding a URL segment. May hold its own `layout.psx`.
`_private/`	Opts the folder and everything under it out of routing entirely.

.psx is the JSX-style source. The runtime executes the compiled *.psx.php sibling — produced automatically in dev (APP_ENV=dev) or by vendor/bin/usephp compile src/Pages at deploy time. Plain .php page files also work and skip the compile step.

Compiled routes (production). By default the router scans src/Pages/ on every request. Run vendor/bin/relayer routes:compile at deploy and it writes a readable, portable snapshot to var/cache/routes/routes.php; production then reads that one OPcache-warm file instead of walking the tree. It is presence-gated — no file means a live scan, so dev always reflects the current tree and never goes stale. Scan-time ambiguities (page/route.php clashes, route-group URL collisions) fail the compile at deploy rather than on the first request.

Class-style page

<?php
// src/Pages/users/[id]/page.psx
declare(strict_types=1);

namespace App\Pages\Users;

use App\Service\UserRepository;
use Polidog\UsePhp\Runtime\Element;
use Polidog\Relayer\Router\Component\PageComponent;

final class UserDetailPage extends PageComponent
{
    public function __construct(private readonly UserRepository $users) {}

    public function render(): Element
    {
        $user = $this->users->find($this->getParam('id'));
        return <h1>{$user->name}</h1>;
    }
}

Constructor injection runs through the DI container — see Injecting Services Into Pages.

Function-style page

You can return a closure instead of declaring a class. The factory closure is autowired the same way class-style page constructors are: declare any typed parameter and the framework will inject it.

<?php
// src/Pages/about/page.psx
return fn() => <main><h1>About</h1></main>;

Services from the container are resolved by type — PageContext is the per-request handle, every other typed parameter comes from the DI container:

<?php
// src/Pages/users/page.psx
declare(strict_types=1);

use App\Service\UserRepository;
use Polidog\Relayer\Router\Component\PageContext;
use Polidog\UsePhp\Runtime\Element;

return function (PageContext $ctx, UserRepository $users): Closure {
    $ctx->metadata(['title' => 'Users']);

    return function () use ($users): Element {
        $list = $users->all();
        return <ul>{...\array_map(fn($u) => <li>{$u->name}</li>, $list)}</ul>;
    };
};

The factory closure runs once per request. The inner render closure runs only when the response is not a 304 — keep heavy work there (see Function-style pages: $ctx->cache()).

Layouts

Each layout.psx wraps every page beneath it. Layouts stack:

src/Pages/
  layout.psx          # outer shell
  dashboard/
    layout.psx        # dashboard frame
    page.psx          # /dashboard
    users/
      page.psx        # /dashboard/users — sees both layouts

Error pages

A root error.psx (extending ErrorPageComponent) renders error responses inside the root layout — an unmatched route (404) and every $ctx->abort() status. It receives the status and message via ErrorPageComponent, so one error.psx can branch on getStatusCode() for a 404 vs. 403 vs. 500 page. Without one, the framework emits a minimal default document.

Control flow: `redirect()` / `notFound()` / `abort()`

A page factory or action handler signals an HTTP outcome by intent, never by touching http_response_code() / header(). Each throws and unwinds — code after the call does not run — and the router turns it into the right response:

Call	Result
`$ctx->redirect($to, $status = 303)`	`Location` response. Default 303 See Other — correct after a POST (Post/Redirect/Get).
`$ctx->notFound()`	`404` → `error.psx` / fallback. Alias for `abort(404)`.
`$ctx->abort($status)`	Any `4xx`/`5xx` → `error.psx` with that status / fallback. Non-error codes throw `InvalidArgumentException`.

return function (PageContext $ctx) use ($posts): Closure {
    $post = $posts->find($ctx->params['id']) ?? $ctx->notFound();
    if ($post->isDraft && null === $ctx->user()) {
        $ctx->abort(403);
    }

    return fn (): Element => <article>{$post->title}</article>;
};

From a route.php handler these stay on the JSON surface: notFound() / abort() become a JSON error with that status (never the HTML error page), while redirect() still produces a content-type-neutral Location response. http_response_code() stays a framework internal — the one place you still set a status by hand is middleware.php, which has no PageContext (it runs before route dispatch).

API Routes

A route.php file is a JSON endpoint instead of a rendered page. It returns a map keyed by HTTP method; each handler is autowired exactly like a function-style page factory (PageContext, Request, Identity, and container services inject by type) and returns a Response — no layout or HTML pipeline runs. This mirrors Next.js Route Handlers (method-keyed handlers + a Response object), adapted to PHP: the map stays the declaration-free contract (a route.php is required fresh per request, so top-level function GET() is not an option), while autowiring is kept because it is consistent with how pages resolve their arguments.

<?php
// src/Pages/api/users/route.php
declare(strict_types=1);

use App\Service\UserRepository;
use Polidog\Relayer\Http\Request;
use Polidog\Relayer\Http\Response;

return [
    'GET'  => fn (UserRepository $users): Response => Response::json(['users' => $users->all()]),
    'POST' => function (Request $req, UserRepository $users): Response {
        $users->create($req->allPost());
        return Response::json(['ok' => true], 201);
    },
];

Lives in src/Pages/ alongside pages, with the same [param] dynamic segments — read them via $ctx->params['id']. A directory is a page or a route, not both (the scanner errors if it finds both).
A handler must return a Response. Build it with Response::json($data, $status, $headers) (encodes + sets Content-Type: application/json, slashes/unicode unescaped), Response::text(), Response::noContent() (a bodyless 204 by default), Response::redirect($location, $status), or Response::make() for a raw body. Status and headers are always explicit — there is no raw-data return path; returning anything else is a hard server error.
OPTIONS and HEAD are synthesized to match Next.js: an undeclared OPTIONS → 204 + Allow, an undeclared HEAD runs the GET handler and drops the body. An explicit handler for either always wins. A method with no handler (and not synthesizable) → 405 + Allow (JSON body).
route.php must only return the map (no class/function declarations); it is re-evaluated every request.
Auth uses the same $ctx->requireAuth() / Identity mechanism as pages, but a failure is a JSON 401 (anonymous) or 403 (wrong role) — not the HTML-login 302 pages emit. $ctx->notFound() / $ctx->abort() likewise become a JSON error with that status (never the HTML error page); $ctx->redirect() still produces a content-type-neutral Location response (a deliberate handler action, not an error gate).

Per-page scripts (`$ctx->js()` / `addJs()`)

A page (or any layout above it) can declare its own external scripts instead of everything riding the one global bundle. Function-style:

return function (PageContext $ctx): Closure {
    $ctx->js('/assets/chart.js', defer: true);

    return fn (): Element => <canvas id="chart"></canvas>;
};

Class-style pages and layouts get the same via $this->addJs(...):

final class Dashboard extends LayoutComponent
{
    public function render(): Element
    {
        $this->addJs('/assets/dashboard.js', module: true);
        return <div>{...$this->getChildren()}</div>;
    }
}

Emitted at the end of <body>, after the main usePHP bundle, in declaration order. Layout scripts come before the page's; an outer (root) layout before an inner one.
src-only by design. Flags: defer, async, module (type="module"). For inline JS use $document->addHeadHtml() — the same hook the Island loader rides on (below).
No deduplication — a layout and a page both declaring the same src produce two tags. Declared, not reconciled (mirrors metadata()).

React Islands (rich-UI escape hatch)

When a page genuinely needs a rich client UI the server-rendered defer/partial model can't express, mount a real React component as an island: the server still owns the page, one node is handed to React with initial props from PHP.

<?php
// src/Pages/dashboard/page.psx
declare(strict_types=1);

use Polidog\Relayer\React\Island;
use Polidog\Relayer\Router\Component\PageContext;

return fn (PageContext $ctx) => (
    <section>
        <h1>Dashboard</h1>
        {Island::mount('Chart', ['points' => $ctx->params])}
    </section>
);

Island::mount() renders <div data-react-island="Chart" data-react-props='…'></div>. Add the framework's tiny, React-agnostic loader once via the document, then your bundle:

$document->addHeadHtml(Island::loaderScript());
$document->addHeadHtml('<script type="module" src="/islands.js"></script>');

You own islands.js — build it with your own toolchain (vite / esbuild), with React bundled in. The contract is one call:

import { createRoot } from 'react-dom/client';
import Chart from './islands/Chart';

window.relayerIslands.register('Chart', (el, props) => {
    createRoot(el).render(<Chart {...props} />);
});

The framework provides only the PHP primitive and the loader — it stays Node-free. React, JSX, and bundling are yours. The loader finds islands (including ones swapped in by usePHP defer/partial, via a MutationObserver), parses props, and calls your registered mount fn; registration and DOM order are interchangeable.
Props flow one way (PHP → initial props). For anything the island needs from the server afterwards, fetch your JSON API routes (route.php) — there is no separate island↔server channel.
Names must be plain identifiers; non-encodable props raise a clear error.
One intentional residual: there is no SSR (client render only — the mount node is empty until hydration; render a loading state inside your component). loaderScript() is an inline <script>; under a strict script-src CSP pass loaderScript($nonce) and it is emitted as <script nonce="…"> (the window.relayerIslands.register contract is unchanged).

Middleware

An optional root src/Pages/middleware.php wraps every page/route dispatch. It returns a single closure fn(Request $request, Closure $next); call $next($request) to continue to the matched route, or don't call it to short-circuit (CORS preflight, rate-limit, maintenance mode, …):

<?php
// src/Pages/middleware.php
declare(strict_types=1);

use Polidog\Relayer\Http\Request;

return function (Request $request, Closure $next): void {
    if (null === $request->header('x-api-key')) {
        \http_response_code(401);
        echo '{"error":"missing api key"}';
        return; // route never runs
    }
    $next($request);
};

One closure, no chain runner (by design). To run several things, compose by hand: fn ($r, $next) => $a($r, fn ($r) => $b($r, $next)).
required fresh each request (declaration-free, like route.php); a non-closure return is a clear error. The framework defer/profiler endpoints deliberately run outside it.

CORS ships as a ready-made middleware — the one provided implementation, not a parallel system:

<?php
// src/Pages/middleware.php
use Polidog\Relayer\Http\Cors;

return Cors::middleware([
    'origins' => ['https://app.example.com'], // or ['*']
    // methods / headers / credentials / maxAge are optional
]);

It answers OPTIONS preflights with 204 itself and adds Access-Control-Allow-Origin to actual requests. credentials: true with origins: ['*'] reflects the request Origin (a literal * is invalid with credentials per spec).

Inspecting routes

vendor/bin/relayer routes prints every route Relayer discovers under src/Pages — pages and route.php endpoints with their methods — using the same scanner the router uses:

METHODS    PATH            TYPE  FILE
GET,POST   /               page  src/Pages/page.psx
GET,POST   /api/users      api   src/Pages/api/users/route.php
GET,POST   /users/[id]     page  src/Pages/users/[id]/page.psx

Pages report GET,POST (POST is how server actions / useState reach a page); API routes list their declared methods. A route.php that fails to load is shown as ? with a warning line, not silently hidden.

Server Actions (form / CSRF-protected)

Dispatch a form submission to a server-side handler bound to the page (equivalent to Next.js Server Actions). The token is CSRF-protected and the handler runs before render(). Available in both class- and function-style pages.

Class-style: `PageComponent::action()`

PageComponent::action([$this, 'handler']) returns a CSRF-bound token for a form's hidden field. Submitting the form invokes the matching method on the page before render():

public function render(): Element
{
    return (
        <form method="post">
            <input type="hidden" name="_usephp_action" value={$this->action([$this, 'save'])} />
            <input name="title" />
        </form>
    );
}

public function save(array $form): void
{
    // ... handle $form['title']
    header('Location: /dashboard', true, 303); // PRG
    exit;
}

Invalid CSRF tokens return a 403.

Function-style: `PageContext::action()`

Function-style pages declare server actions through PageContext::action(). The factory closure runs on every request — including the POST that submits the form — so the action table is rebuilt before dispatch and the token only needs to carry (pageId, name):

<?php
// src/Pages/users/page.psx
declare(strict_types=1);

use App\Service\UserRepository;
use Polidog\Relayer\Router\Component\PageContext;
use Polidog\UsePhp\Runtime\Element;

return function (PageContext $ctx, UserRepository $users): Closure {
    $save = $ctx->action('save', function (array $form) use ($users, $ctx): void {
        $users->create($form['name']);
        $ctx->redirect('/users'); // 303 Post/Redirect/Get; unwinds here
    });

    return function () use ($save, $users): Element {
        return (
            <main>
                <ul>{...\array_map(fn($u) => <li>{$u->name}</li>, $users->all())}</ul>
                <form action={$save}>
                    <input name="name" />
                    <button>save</button>
                </form>
            </main>
        );
    };
};

The handler receives the POST body as its first argument (with _usephp_action / _usephp_csrf stripped). Action names must be unique per page — registering the same name twice throws.

Binding arguments

A third $args argument binds values into the handler. They are passed after the form body:

// list → positional:   handler($form, 42)
$delete = $ctx->action('delete', function (array $form, int $id) use ($repo): void {
    $repo->delete($id);
}, [$user->id]);

// assoc → named args:   handler(formData: $form, id: 42)
$ctx->action('delete', fn (array $formData, int $id) => $repo->delete($id), ['id' => $user->id]);

$args is embedded verbatim in the base64 action token (it is not signed — tamper detection is the CSRF token's job). Keep bound values to identifiers and always re-validate authorization/integrity inside the handler (e.g. verify ownership of the incoming $id server-side).

Re-rendering after a failed submit

A function-style page's factory closure re-runs on every request and the action handler runs after the renderer is built. To re-render the same page on a validation error, capture state by reference (&$errors) and read the post-dispatch value in the renderer (the typical pairing with Validation's safeParse; full example in example/src/Pages/signup/page.psx):

return function (PageContext $ctx) use ($schema): Closure {
    $errors = [];
    $save = $ctx->action('save', function (array $form) use ($schema, &$errors, $ctx): void {
        $result = $schema->safeParse($form);
        if (!$result->success) { $errors = $result->errors; return; }
        // ... on success: $ctx->redirect('/users') (303 Post/Redirect/Get)
    });

    // $errors is mutated after the action runs → capture by reference
    return function () use ($save, &$errors): Element { /* render $errors */ };
};

Service Registration

You have two complementary ways to register services. Both can be used in the same project — YAML/PHP files load first, then AppConfigurator runs and can override anything.

Option A — `config/services.yaml` (auto-loaded)

Drop a config/services.yaml next to composer.json and the framework picks it up at boot time. This is the idiomatic Symfony style:

# config/services.yaml
services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: true

  App\Service\PdoUserRepository: ~

  App\Service\UserRepository:
    alias: App\Service\PdoUserRepository

config/services.php (returning a ContainerConfigurator closure) and config/services.yml are also accepted.

Option B — `AppConfigurator` (PHP)

Subclass AppConfigurator and register services on the ContainerBuilder. The framework applies autowire + public visibility by default, so a bare register() call is usually enough:

<?php
// src/PagesConfigurator.php
declare(strict_types=1);

namespace App;

use App\Service\UserRepository;
use App\Service\PdoUserRepository;
use Polidog\Relayer\AppConfigurator as BaseConfigurator;
use Symfony\Component\DependencyInjection\ContainerBuilder;

final class AppConfigurator extends BaseConfigurator
{
    public function configure(ContainerBuilder $container): void
    {
        $container->register(PdoUserRepository::class);
        $container->setAlias(UserRepository::class, PdoUserRepository::class)
            ->setPublic(true);
    }
}

Then pass it to boot():

Relayer::boot(__DIR__ . '/..', new App\AppConfigurator(__DIR__ . '/..'))->run();

Autowire defaults

The framework iterates every Definition you register and:

enables autowired if you didn't pass explicit constructor arguments
forces public = true so PSR-11 get($id) can fetch it

If you need a private service or fully-manual wiring, configure the Definition explicitly — your settings win.

Injecting Services Into Pages

Class-based pages get constructor injection automatically. Page classes do not need to be registered in the container — the PSR-11 adapter falls back to reflection-based autowiring for unregistered classes, resolving each typed dependency from the Symfony container:

<?php
// src/Pages/users/page.psx
declare(strict_types=1);

namespace App\Pages\Users;

use App\Service\UserRepository;
use Polidog\UsePhp\Runtime\Element;
use Polidog\Relayer\Router\Component\PageComponent;

final class UsersPage extends PageComponent
{
    public function __construct(private readonly UserRepository $users)
    {
    }

    public function render(): Element
    {
        $users = $this->users->all();
        // ...
    }
}

You only need to register a Page in AppConfigurator if you want non-default behavior (e.g. service tags, decorators, factory construction).

Accessing the HTTP Request

Declare a Polidog\Relayer\Http\Request parameter on a page (function-style factory or class constructor) and the framework will inject an immutable snapshot of the current request — pages never need to touch $_GET, $_POST, or $_SERVER directly.

<?php
// src/Pages/signup/page.psx
declare(strict_types=1);

use Polidog\Relayer\Http\Request;
use Polidog\Relayer\Router\Component\PageContext;
use Polidog\UsePhp\Runtime\Element;

return function (PageContext $ctx, Request $req): Closure {
    $errors = [];

    if ($req->isPost()) {
        $email = $req->post('email') ?? '';
        if (!\filter_var($email, \FILTER_VALIDATE_EMAIL)) {
            $errors['email'] = 'Invalid email';
        }
        if ([] === $errors) {
            $ctx->redirect('/thanks'); // 303 Post/Redirect/Get; unwinds here
        }
    }

    return function () use ($errors, $req): Element {
        // ... render form, echoing $req->post('email') back into the input
    };
};

Request API (all immutable):

Method	Returns
`$req->method`	uppercase HTTP method
`$req->path`	request path (no query string)
`$req->isGet()` / `isPost()`	`bool`
`$req->isMethod('PUT')`	`bool`
`$req->post($key)`	`?string` (null if missing / non-string)
`$req->query($key)`	`?string`
`$req->header($name)`	`?string` (case-insensitive)
`$req->allPost()`	`array<string, mixed>` (raw body)
`$req->allQuery()`	`array<string, mixed>`
`$req->allHeaders()`	`array<string, string>` (lowercased keys)

Tests use new Request(method: 'POST', path: '/signup', post: [...]) directly — no superglobal manipulation needed.

Authentication

Session-based authentication ships in the box. You provide a UserProvider (your user lookup) and the framework wires the rest: password hashing, the session-stored principal, and a request-time guard that protects pages.

1. Implement a `UserProvider`

The provider takes a user-supplied identifier (typically email) and returns Credentials — the Identity that will live in the session, plus the password hash to verify against. Return null when the identifier is unknown.

<?php
declare(strict_types=1);

namespace App\Auth;

use Polidog\Relayer\Auth\Credentials;
use Polidog\Relayer\Auth\Identity;
use Polidog\Relayer\Auth\UserProvider;

final class PdoUserProvider implements UserProvider
{
    public function __construct(private readonly \PDO $pdo) {}

    public function findByIdentifier(string $identifier): ?Credentials
    {
        $stmt = $this->pdo->prepare(
            'SELECT id, name, password_hash, roles FROM users WHERE email = ?'
        );
        $stmt->execute([\strtolower(\trim($identifier))]);
        $row = $stmt->fetch(\PDO::FETCH_ASSOC);
        if (false === $row) {
            return null;
        }

        return new Credentials(
            identity: new Identity(
                id: (int) $row['id'],
                displayName: (string) $row['name'],
                roles: \json_decode((string) $row['roles'], true) ?: [],
            ),
            passwordHash: (string) $row['password_hash'],
        );
    }
}

2. Bind the provider

The framework registers Authenticator, PasswordHasher (NativePasswordHasher with PASSWORD_DEFAULT), and SessionStorage (NativeSession) by default. Adding the UserProvider binding is all that's required to opt in:

# config/services.yaml
services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: true

  App\Auth\PdoUserProvider: ~

  Polidog\Relayer\Auth\UserProvider:
    alias: App\Auth\PdoUserProvider

Apps that don't bind UserProvider pay nothing — Authenticator is only registered when the interface is bound, so unrelated projects keep booting unchanged.

3. Log users in

Inject Authenticator into the login page and call attempt() with the submitted credentials. Successful authentication rotates the session id (defends against session fixation) and stores the Identity snapshot.

<?php
// src/Pages/login/page.psx
declare(strict_types=1);

use Polidog\Relayer\Auth\Authenticator;
use Polidog\Relayer\Router\Component\PageContext;
use Polidog\UsePhp\Runtime\Element;

return function (PageContext $ctx, Authenticator $auth): Closure {
    $error = null;

    $login = $ctx->action('login', function (array $form) use ($auth, &$error, $ctx): void {
        $identity = $auth->attempt(
            (string) ($form['email']    ?? ''),
            (string) ($form['password'] ?? ''),
        );

        if (null === $identity) {
            $error = 'Invalid email or password.';

            return;
        }

        $ctx->redirect('/dashboard'); // 303 Post/Redirect/Get; unwinds here
    });

    return function () use ($login, $error): Element {
        // ... render form, surface $error as a single generic message
    };
};

Authenticator API:

Method	Returns	Notes
`attempt($id, $password)`	`?Identity`	Verify via `UserProvider` + hasher; on success: log in.
`login(Identity $identity)`	`void`	Promote an already-resolved principal (SSO, signup).
`logout()`	`void`	Drop the principal, rotate the session id.
`user()`	`?Identity`	Currently-logged-in principal, or `null`.
`check()`	`bool`	Shorthand for `user() !== null`.
`hasRole($role)` / `hasAnyRole`	`bool`	Role probes.

attempt() runs the password hasher even when the identifier is unknown so an attacker can't enumerate accounts by response time. A failure always returns null; the caller should render a single generic error rather than disclose which field rejected the input.

4. Protect pages

Class-style: `#[Auth]`

Attach Polidog\Relayer\Auth\Auth to a PageComponent subclass. The guard runs in InjectorContainer before the page is instantiated — so an anonymous request never builds the page or its dependencies.

<?php
namespace App\Pages;

use Polidog\Relayer\Auth\Auth;
use Polidog\Relayer\Router\Component\PageComponent;

#[Auth] // any authenticated user
final class DashboardPage extends PageComponent { /* ... */ }

#[Auth(roles: ['admin'])] // role-gated; non-admin gets 403
final class AdminPage extends PageComponent { /* ... */ }

#[Auth(redirectTo: '')] // empty redirect -> 401 instead of 302 (JSON / API)
final class ApiEndpoint extends PageComponent { /* ... */ }

Parameter	Default	Effect
`roles`	`[]`	One of these roles must be present (empty = any user).
`redirectTo`	`'/login'`	Where anonymous requests go. Empty string → `401`.

Anonymous requests get a 302 Location: /login?next=<requested-path> (URL-encoded, same-origin only). Authenticated users lacking the required role get 403 Forbidden.

#[Auth] is evaluated before #[Cache], so unauthorized requests never produce a cacheable 304 that could leak to anonymous viewers through a shared cache. Combining #[Auth] + #[Cache] is fine — just prefer Cache-Control: private for per-user gated pages.

Function-style: `$ctx->requireAuth()` / `Identity` injection

Function-style factories use a declarative guard on PageContext:

<?php
// src/Pages/dashboard/page.psx
declare(strict_types=1);

use Polidog\Relayer\Router\Component\PageContext;
use Polidog\UsePhp\Runtime\Element;

return function (PageContext $ctx): Closure {
    $user = $ctx->requireAuth(); // throws AuthorizationException on failure

    return fn(): Element => <h1>Welcome, {$user->displayName}</h1>;
};

requireAuth($roles = [], $redirectTo = '/login') returns the Identity so you can use it inline. AppRouter catches the exception and produces the same 302 / 401 / 403 response as #[Auth].

For pages that adapt to the authentication state instead of requiring it, declare ?Identity on the factory and the framework injects the current principal (null when no one is logged in):

return function (PageContext $ctx, ?Identity $user): Closure {
    $ctx->metadata(['title' => $user?->displayName ?? 'Welcome']);

    return fn(): Element => null !== $user
        ? <p>Hi, {$user->displayName}</p>
        : <a href="/login">Sign in</a>;
};

A non-nullable Identity parameter is treated as "auth required" and triggers the same redirect path as requireAuth() when anonymous — equivalent to #[Auth] for class-style pages.

5. Pluggable parts

The defaults are sensible but swappable. Bind a different implementation in services.yaml (or AppConfigurator) to override:

Interface	Default	Override when…
`Polidog\Relayer\Auth\UserProvider`	(unbound, app-supplied)	Always — this is your user lookup.
`Polidog\Relayer\Auth\PasswordHasher`	`NativePasswordHasher`	You want a specific algorithm or pepper.
`Polidog\Relayer\Auth\SessionStorage`	`NativeSession`	You want Redis / database-backed sessions.

NativePasswordHasher uses PASSWORD_DEFAULT so it tracks whatever PHP considers strongest on the current build (bcrypt today). Force argon2id when libargon2 is available:

$container->register(NativePasswordHasher::class)
    ->setArguments([\PASSWORD_ARGON2ID]);

NativeSession calls session_start() lazily on first read/write, so just resolving the service through DI does not eagerly emit Set-Cookie. It shares $_SESSION with the existing CSRF token machinery — no duplicate session starts.

Notes

The auth guard runs in InjectorContainer (class-style pages) and in the factory-arg resolver (Identity injection / requireAuth). Layouts are not guarded — they're resolved separately. If you need layout-level auth state, inject ?Authenticator into the layout constructor and read $auth?->user() from render().
?next=<path> on the login redirect is same-origin only — paths starting with // or an absolute URL are dropped to prevent open-redirect bouncing off the login page.
Sessions are rotated on both login and logout. A pre-login session id captured by an attacker stops working the moment the user authenticates.

6. Token authentication (Firebase / Cognito)

For apps where a client SDK already mints a signed ID token — the Firebase JS SDK, AWS Amplify, the Cognito Hosted UI — the framework verifies that token instead of running a password handshake. It owns no OAuth redirect / code-exchange flow: the client holds the token and sends it as Authorization: Bearer <jwt>; Relayer validates the signature against the IdP's published JWKS and the registered claims (iss, aud, exp/nbf/iat, and token_use for Cognito).

Bind a `TokenVerifier`

TokenVerifier is the token-based counterpart of UserProvider. Build one with the Firebase / Cognito factory. Symfony's service factory syntax keeps it to config — no glue class:

# config/services.yaml
services:
  _defaults: { autowire: true, autoconfigure: true, public: true }

  # Firebase
  Polidog\Relayer\Auth\Token\TokenVerifier:
    factory: ['Polidog\Relayer\Auth\Token\Firebase', 'verifier']
    arguments:
      $http: '@Polidog\Relayer\Http\Client\HttpClient'
      $projectId: '%env(FIREBASE_PROJECT_ID)%'
      $cacheDir: '%app.project_root%/var/cache/jwks'

  # …or Cognito
  # Polidog\Relayer\Auth\Token\TokenVerifier:
  #   factory: ['Polidog\Relayer\Auth\Token\Cognito', 'verifier']
  #   arguments:
  #     $http: '@Polidog\Relayer\Http\Client\HttpClient'
  #     $region: '%env(COGNITO_REGION)%'
  #     $userPoolId: '%env(COGNITO_USER_POOL_ID)%'
  #     $appClientId: '%env(COGNITO_APP_CLIENT_ID)%'
  #     $cacheDir: '%app.project_root%/var/cache/jwks'

Env var	Used by	Example
`FIREBASE_PROJECT_ID`	Firebase	`my-app`
`COGNITO_REGION`	Cognito	`ap-northeast-1`
`COGNITO_USER_POOL_ID`	Cognito	`ap-northeast-1_AbCdEf`
`COGNITO_APP_CLIENT_ID`	Cognito	`7f3k…` (app client id)

The JWKS is fetched through the framework's own HttpClient (so it lands in the dev profiler like any other egress) and cached on disk per URL, honouring the response's Cache-Control: max-age. Key rotation is automatic: a token whose kid is missing from the cached set triggers exactly one refresh (rate-limited, so forged kids can't be amplified into a JWKS-fetch flood). An unreachable JWKS endpoint is an operational fault — it surfaces as a server error, it does not silently log everyone out.

Mode A — stateless API (bearer per request)

Bind only a TokenVerifier (no UserProvider). AuthenticatorInterface then resolves to the stateless TokenAuthenticator, so the same #[Auth] / requireAuth() machinery works unchanged — every request re-derives the principal from the bearer header, nothing is persisted:

#[Auth(redirectTo: '')]            // 401 for an absent/bad token (no redirect)
final class ApiEndpoint extends PageComponent { /* ... */ }

#[Auth(roles: ['admin'])]          // roles read from the token's claims
final class AdminApi extends PageComponent { /* ... */ }

Mode B — session login (verify once, then a cookie session)

Verify the token in a login route and hand the resulting Identity to Authenticator::login(). The session Authenticator no longer needs a UserProvider, so a Firebase/Cognito app with no local password store still gets a normal cookie session and all the session-based #[Auth] behaviour after the first request:

<?php
// src/Pages/auth/token/route.php — POST { } with Authorization: Bearer <jwt>
declare(strict_types=1);

use Polidog\Relayer\Auth\Authenticator;
use Polidog\Relayer\Auth\Token\BearerToken;
use Polidog\Relayer\Auth\Token\TokenVerifier;
use Polidog\Relayer\Auth\Token\AuthorizationHeader;
use Polidog\Relayer\Http\Response;

return [
    'POST' => static function (
        TokenVerifier $verifier,
        Authenticator $auth,
        AuthorizationHeader $header,
    ): Response {
        $identity = $verifier->verify(
            BearerToken::parse($header->value()) ?? '',
        );
        if (null === $identity) {
            return Response::json(['error' => 'invalid token'], 401);
        }

        $auth->login($identity);             // rotates the session id

        return Response::json(['user' => $identity->toArray()]);
    },
];

Precedence (one rule, no hybrid)

Bound services	`AuthenticatorInterface` is…	Notes
`UserProvider`	session `Authenticator`	Password app (today's behaviour).
`TokenVerifier` only	`TokenAuthenticator`	Token-first API; `#[Auth]` enforces the bearer token.
both	session `Authenticator`	Session-first; `TokenAuthenticator` is still injectable by type on specific API routes.

Notes

Bearer only. The token is read from Authorization: Bearer …. On Apache/CGI the Authorization header is often stripped unless an .htaccess/vhost rule re-injects it — Relayer also reads the documented REDIRECT_HTTP_AUTHORIZATION fallback, but the rewrite rule must still be present on those hosts.
Pluggable claim mapping. Both factories take an optional identityMapper closure (fn(\stdClass $claims): ?Identity) to map custom claims / role sources; the defaults use sub as the id, fall back name → email → sub for the display name (Cognito also tries cognito:username), and read roles from cognito:groups (Cognito) or a custom roles array (Firebase).
attempt() / login() / logout() on TokenAuthenticator throw LogicException — a stateless bearer authenticator has no password handshake and no session; failing loudly beats a misleading no-op.

HTTP Cache Headers via `#[Cache]`

Attach Polidog\Relayer\Http\Cache to a Page class to control Cache-Control / Vary / ETag headers. The framework reads the attribute when AppRouter resolves the page through the container and emits the headers before the body is written.

<?php
// src/Pages/page.psx
declare(strict_types=1);

namespace App\Pages;

use Polidog\Relayer\Router\Component\PageComponent;
use Polidog\Relayer\Http\Cache;
use Polidog\UsePhp\Runtime\Element;

#[Cache(
    maxAge: 3600,
    sMaxAge: 86400,
    public: true,
    vary: ['Accept-Language'],
    etag: 'home-v1',
)]
final class HomePage extends PageComponent
{
    public function render(): Element { /* ... */ }
}

Supported parameters:

Parameter	Effect
`maxAge`	`Cache-Control: max-age=<n>`
`sMaxAge`	`Cache-Control: s-maxage=<n>` (CDN)
`public`	`Cache-Control: public`
`private`	`Cache-Control: private`
`noStore`	`Cache-Control: no-store`
`noCache`	`Cache-Control: no-cache`
`mustRevalidate`	`Cache-Control: must-revalidate`
`immutable`	`Cache-Control: immutable`
`vary`	`Vary: <comma-joined values>`
`etag`	`ETag: "<value>"` (auto-quoted if raw)
`etagWeak`	Emit ETag as a weak validator `W/"…"`
`lastModified`	`Last-Modified: <RFC 7231 GMT date>` (any `strtotime()`-parseable string; UTC recommended)
`etagKey`	Logical key looked up in the configured `EtagStore` (see below). Static `etag` wins when both are set.

Conditional GET / `304 Not Modified`

When etag or lastModified is set, the framework also evaluates the request's If-None-Match / If-Modified-Since headers on safe methods (GET, HEAD). If the client already has a fresh copy, the response is short-circuited:

cache validation headers (ETag, Last-Modified, Cache-Control, Vary) are emitted
status is set to 304 Not Modified
the request terminates before any body is rendered

ETag comparison follows the weak comparison rules of RFC 7232 §2.3.2, so W/"v1" and "v1" match each other and * matches any tag.

Example

#[Cache(
    maxAge: 3600,
    public: true,
    vary: ['Accept-Language'],
    etag: 'home-v1',
    etagWeak: true,
    lastModified: '2025-01-15 10:00:00 UTC',
)]
final class HomePage extends PageComponent { /* ... */ }

Function-style pages: `$ctx->cache()`

PHP attributes only attach to classes, so function-style page.psx files declare their cache policy through PageContext instead:

<?php
// src/Pages/feed/page.psx
declare(strict_types=1);

use Polidog\Relayer\Http\Cache;
use Polidog\Relayer\Router\Component\PageContext;
use Polidog\UsePhp\Runtime\Element;

return function (PageContext $ctx): Closure {
    // Lightweight setup: declare cache, read params. NO DB queries here.
    $ctx->cache(new Cache(maxAge: 60, public: true, etagKey: 'feed'));

    return function () use ($ctx): Element {
        // Heavy work goes here — only runs on cache miss.
        // ... query DB, build the page
    };
};

The factory closure runs once per request (lightweight); the inner render closure runs only when the response is not a 304. So the 304 short-circuit saves the inner closure's body — keep DB/expensive work there to get the same "never touch the database" benefit class-style pages get.

All #[Cache] parameters are available on the Cache constructor.

Dynamic ETag via `EtagStore`

A static etag: 'home-v1' works for content that only changes on deploy. For data-driven pages, declare etagKey: and let an EtagStore resolve the current value at request time:

#[Cache(maxAge: 60, public: true, etagKey: 'user-list')]
final class UsersPage extends PageComponent { /* ... */ }

The framework looks up the key in the registered EtagStore before constructing the page. If the client's If-None-Match already matches, the request is short-circuited with 304 and no page or repository code runs — the database is never touched.

Producers (repositories, command handlers) update the stored value when their data changes:

final class UserRepository
{
    public function __construct(private readonly EtagStore $etags) {}

    public function save(User $user): void
    {
        // ... persist
        $this->etags->set('user-list', \sha1((string) \microtime(true)));
    }
}

Default backend: `FileEtagStore`

Out of the box the framework registers FileEtagStore writing to $projectRoot/var/cache/etags/ (one file per sha1(key), atomic write-then-rename). Zero configuration needed.

Custom backend (e.g. Redis)

Implement Polidog\Relayer\Http\EtagStore and register your class as the EtagStore alias. For example, with phpredis:

final class RedisEtagStore implements EtagStore
{
    public function __construct(
        private readonly \Redis $redis,
        private readonly string $prefix = 'etag:',
    ) {}

    public function get(string $key): ?string
    {
        $value = $this->redis->get($this->prefix . $key);
        return \is_string($value) && $value !== '' ? $value : null;
    }

    public function set(string $key, string $etag): void
    {
        $this->redis->set($this->prefix . $key, $etag);
    }

    public function forget(string $key): void
    {
        $this->redis->del($this->prefix . $key);
    }
}

Then wire it through services.yaml:

services:
  _defaults:
    autowire: true
    public: true

  Redis:
    factory: ['App\Factory\RedisFactory', 'connect']

  App\Infrastructure\RedisEtagStore: ~

  Polidog\Relayer\Http\EtagStore:
    alias: App\Infrastructure\RedisEtagStore

…or in AppConfigurator::configure():

$container->register(RedisEtagStore::class);
$container->setAlias(EtagStore::class, RedisEtagStore::class)->setPublic(true);

Notes / caveats

The attribute is honored only on PageComponent subclasses. Layouts and ordinary services with #[Cache] are ignored to avoid surprising header writes when fetched through the container.
All header writes are skipped once headers_sent() is true.
The 304 short-circuit issues exit; from the PSR-11 adapter. It runs before the page is instantiated, so neither the page constructor nor its injected dependencies execute on a cache hit.
If you need conditional cache policy (per-request, per-user), set headers manually inside render() instead.

Database

A thin PDO wrapper: raw SQL in, plain arrays out. No query builder, no SQL-file loader — pass SQL with named (:id) or positional (?) placeholders directly. It exists to give you four things you'd otherwise wire by hand: profiler visibility, explicit timeouts, one error type, and per-request read memoization.

Enable it

The DB layer is registered only when DATABASE_DSN is set — apps that don't use a database pay nothing and don't need to configure anything.

DATABASE_DSN=mysql:host=127.0.0.1;dbname=app;charset=utf8mb4
DATABASE_USER=app
DATABASE_PASSWORD=secret
DATABASE_TIMEOUT=5            # connect timeout, seconds (PDO::ATTR_TIMEOUT)
DATABASE_READ_TIMEOUT=10      # MySQL read timeout, seconds (optional)

DATABASE_DSN is a standard PDO DSN, so SQLite (sqlite:/path/app.db), PostgreSQL (pgsql:host=...), etc. all work. DATABASE_READ_TIMEOUT is applied only for mysql: DSNs.

Use it

Take a Database dependency in a page or component constructor:

use Polidog\Relayer\Db\Database;

final class UserPage extends PageComponent
{
    public function __construct(private readonly Database $db) {}

    public function render(): string
    {
        $user = $this->db->fetchOne(
            'SELECT id, name FROM users WHERE id = :id',
            ['id' => 42],
        );
        // ...
    }
}

Method	Returns
`fetchAll($sql, $params)`	`list<array<string,mixed>>`
`fetchOne($sql, $params)`	`array<string,mixed>` or `null`
`fetchValue($sql, $params)`	first column of first row, or `null`
`perform($sql, $params)`	affected row count (`int`)
`lastInsertId($name = null)`	last insert id (`string`)
`transactional($callback)`	callback's return value

$db->transactional(function (Database $tx): void {
    $tx->perform('INSERT INTO orders (user_id) VALUES (?)', [$userId]);
    $tx->perform('UPDATE users SET order_count = order_count + 1 WHERE id = ?', [$userId]);
});

The callback runs inside a transaction — commit on return, rollback + rethrow on any exception. Use the $tx argument it receives so the calls stay traced and cached.

What you get for free

Errors — every driver failure is thrown as a single Polidog\Relayer\Db\DatabaseException; the original PDOException is kept as the previous exception.
Timeouts — a stuck DB surfaces as a DatabaseException within the configured timeout instead of hanging the worker.
Request-scoped cache — identical reads (fetchAll / fetchOne / fetchValue with the same SQL + params) hit an in-process cache for the rest of the request, so a page assembled from several components that each need the same lookup makes one round-trip, not N. Any perform or transactional flushes the cache. It is request-scoped only — no TTL, no cross-request sharing.
Profiler (dev) — every real query is recorded in the request profile as a timed db.query / db.mutate / db.transaction span with the SQL and bound params; cache hits show as db.cache_hit markers so you can see exactly how many round-trips memoization saved. In prod the profiler is a no-op, so there's no overhead.

Fetching external APIs (HTTP client)

A thin ext-curl wrapper for calling external Web APIs. Same decorator stack as the Database layer — contract → concrete → dev tracing → request-scoped cache: pass a method and URL, get an HttpResponse back. No middleware stack, no PSR-18 indirection.

Enable it

HttpClient is always registered. Unlike the DB it needs no required config, so (like the EtagStore) any page or component can take an HttpClient dependency with zero setup. Timeouts come from optional env vars:

HTTP_CLIENT_TIMEOUT=10           # whole-transfer timeout, seconds (CURLOPT_TIMEOUT)
HTTP_CLIENT_CONNECT_TIMEOUT=3    # connect-only timeout, seconds (CURLOPT_CONNECTTIMEOUT)

Left unset, cURL's defaults (no limit) apply.

Use it

Take an HttpClient dependency in a page or component constructor:

use Polidog\Relayer\Http\Client\HttpClient;

final class WeatherPage extends PageComponent
{
    public function __construct(private readonly HttpClient $http) {}

    public function render(): string
    {
        $res = $this->http->get('https://api.example.com/weather?city=tokyo', [
            'Accept' => 'application/json',
        ]);

        if (!$res->ok()) {
            // 4xx/5xx is not an exception — a normal HttpResponse to branch on
            return 'Could not fetch (' . $res->status . ')';
        }

        $data = $res->json();
        // ...
    }
}

Method	Returns
`get($url, $headers = [])`	`HttpResponse`
`request($method, $url, $headers = [], $body = null)`	`HttpResponse`

HttpResponse exposes status / headers / body (public properties) plus ok() (2xx check), json() (decode the JSON body to a PHP value, objects as associative arrays; throws HttpClientException on non-JSON), and header($name) (case-insensitive single-header lookup).

$res = $this->http->request(
    'POST',
    'https://api.example.com/orders',
    ['Content-Type' => 'application/json'],
    json_encode(['item' => 'book']),
);

What you get for free

Errors — every transport failure (DNS, connect, TLS, timeout, truncated body) is thrown as a single Polidog\Relayer\Http\Client\HttpClientException. A 4xx/5xx is not an exception — it's a normal HttpResponse you inspect via status (the same way a SELECT returning zero rows is not a DatabaseException).
Timeouts — a stuck endpoint surfaces as an HttpClientException within the configured timeout instead of hanging the worker.
Request-scoped cache — identical safe requests (GET / HEAD with the same method + URL + headers) hit an in-process cache for the rest of the request. Non-safe methods (POST / PUT / PATCH / DELETE …) are never cached and flush the whole cache first — the same simple, safe choice CachingDatabase makes for perform(). Request-scoped only — no TTL, no cross-request sharing. Redirects are not followed (the 3xx is returned as-is).
Profiler (dev) — every real round-trip is recorded as a timed http.request span with method, URL, status and byte count; cache hits show as http.cache_hit markers. Request headers and bodies are not recorded, so an Authorization header or secret-bearing body never lands in the profile (the same stance TraceableDatabase takes on bound values). In prod the profiler is a no-op, so there's no overhead.

Validation

Polidog\Relayer\Validation is a schema validator inspired by Zod (TypeScript). It coerces and validates input (form fields always arrive as strings) and returns per-field error messages in a single pass. No extra dependency.

Declaring a schema

Build schemas through the Validator facade:

use Polidog\Relayer\Validation\Validator;

$schema = Validator::object([
    'email' => Validator::string()->trim()->email(),
    'name'  => Validator::string()->trim()->min(1, 'Name is required.'),
    'age'   => Validator::int()->min(0)->optional(),
    'role'  => Validator::enum(['admin', 'member'])->default('member'),
]);

Factory	Schema
`Validator::string()`	String. `min/max/length/regex/email/url/trim/lower/upper`
`Validator::int()`	Integer; coerces numeric strings. `min/max/positive/nonNegative`
`Validator::float()`	Float; coerces numeric strings
`Validator::bool()`	Boolean
`Validator::enum([...])`	One of the allowed values; `literal()` for a single one
`Validator::object([...])`	Assoc array; unknown keys stripped by default, `passthrough()` keeps them
`Validator::array($element)`	Validates every element against `$element`
`Validator::email()` / `url()`	Shortcuts for `string()->trim()->email()` / `url()`

Modifiers available on every schema (immutable — each returns a clone, so a base schema is reusable as a building block):

Modifier	Meaning
`optional()`	Absent input becomes `null`; no further checks
`nullable()`	Allows `null` (the key itself is still required)
`default($value)`	Value used when input is absent
`required(?$message)`	Force required + override the "absent" message
`refine($predicate, $msg)`	Arbitrary extra validation predicate
`transform($fn)`	Final transform after a value validates

For StringSchema / IntSchema / EnumSchema an empty string counts as "not provided", so optional / required / default behave intuitively with form inputs.

Parsing

$result = $schema->safeParse($_POST);

if ($result->success) {
    $data = $result->data;          // coerced values
} else {
    $errors = $result->errors;      // ['email' => '...', 'address.zip' => '...']
}

safeParse($input): ParseResult — never throws on validation errors; branch on success.
parse($input): mixed — throws ParseError (carrying $errors) on failure.
Nested object errors use dot paths (address.zip).

With form actions

The typical use is alongside $ctx->action() (example/src/Pages/signup/page.psx):

$schema = Validator::object([
    'name'     => Validator::string()->trim()->min(1, 'Name is required.'),
    'email'    => Validator::string()->trim()->email(),
    'password' => Validator::string()->min(8, 'Password must be at least 8 characters.'),
]);

$signup = $ctx->action('signup', function (array $form) use ($schema, &$errors): void {
    $result = $schema->safeParse($form);
    if (!$result->success) {
        $errors = $result->errors;   // hand field errors to the view
        return;
    }
    // $result->data is coerced
});

Internationalization (i18n)

A dependency-free translator with file-based catalogs, automatic locale resolution, and localized framework messages. Opt-in by configuration: an app that sets no i18n env var stays single-locale English and pays nothing — every framework string is byte-identical to the pre-i18n output.

Configure

APP_LOCALE=en            # default / active locale (default: en)
APP_LOCALES=en,ja        # supported locales (default: just APP_LOCALE)
LOCALE_COOKIE=locale     # cookie name for the cookie source (default: locale)
LOCALE_PATH_PREFIX=true  # opt out of /{locale}/... routing (default: true)

Translator and LocaleResolver are always registered in the container (autowired, public), but locale switching — cookie / Accept-Language / path-prefix resolution — only does anything once APP_LOCALES lists 2+ locales. With none (or a single locale) every request resolves to APP_LOCALE and no path rewriting happens: a route under /en/* keeps working exactly as before i18n existed. LOCALE_PATH_PREFIX=false only opts a multi-locale app out of /{locale}/... routing (cookie / Accept-Language still apply); it cannot turn prefix routing on for a single-locale app — there would be nothing to disambiguate.

APP_LOCALE is the default active locale, not the framework's fallback: the built-in relayer.* messages always fall back to English (the guaranteed-complete shipped catalog), so a missing translation never surfaces a raw key for a framework string.

Locale resolution order

For each request LocaleResolver picks the locale from, highest priority first:

URL path prefix — /{locale}/... when the first segment is a supported locale. This is also the only source that rewrites the path the router matches on, so /ja/about and /about hit the same src/Pages/about/page.psx.
Session — read only when a session is already active. Starting a session purely to detect a locale would emit a per-request Set-Cookie and break CDN caching of anonymous pages, so the resolver never does that; logged-in flows that already have a session get their stored _locale honored.
Cookie — LOCALE_COOKIE (CDN-safe; no session).
Accept-Language — q-value negotiated against the supported list.
Default — APP_LOCALE.

Matching is on the primary subtag (ja-JP matches a supported ja); the resolved value is the canonical spelling from APP_LOCALES. The chosen locale is also written to <html lang="…"> and exposed as $request->locale().

Deferred fragments and path-prefix routing. A <X defer /> sub-request is fetched from a root-absolute /_defer/{name} URL with no /{locale} segment (usePHP roots it), so it never carries the parent page's path prefix. Its locale therefore resolves from the cookie / Accept-Language / default — not from the URL path. If you localize purely via /{locale}/… prefixes and want deferred fragments in the same language, also set the LOCALE_COOKIE (or rely on Accept-Language); the cookie is CDN-safe and is the intended carrier for this case.

Translating your own content

Drop PHP catalogs in <projectRoot>/translations/{locale}.php — flat or nested, merged over (and overriding) the framework catalogs:

// translations/ja.php
return [
    'home.title'   => 'ようこそ',
    'cart.items'   => '{count}点|{count}点', // pipe = plural forms
    'user'         => ['greeting' => 'こんにちは、{name}さん'],
];

Inject the Translator into any page, layout, or service:

use Polidog\Relayer\I18n\Translator;

return static fn (Translator $t) => h('h1', [], $t->trans('home.title'));
// placeholders:  $t->trans('user.greeting', ['name' => $name])
// plural:        $t->transChoice('cart.items', $count)

transChoice() selects a form from a one|other pipe message via a simplified CLDR rule (English-like one/other; single-form for Japanese, Chinese, Korean, …). A missing key degrades to the key itself (after placeholder substitution) — visible, never fatal.

Localized framework messages

Validation messages and HTTP error reason phrases (the HTML error page and the JSON {"error": …} body for API routes) are resolved through the same catalogs under the relayer.* namespace, with en and ja shipped. The Validation schemas are built outside the container, so they reach the active translator through a process-wide ambient holder (Polidog\Relayer\I18n\Translators) that AppRouter sets per request; a custom refine() / required('…') message is always passed through verbatim. CLI output (relayer …) is intentionally English-only for now.

Logger

A PSR-3 logger, backed by Monolog. Apps depend on the standard Psr\Log\LoggerInterface, so the same binding is shared with any third-party library that logs through PSR-3.

Enable it

The logger is always registered. Like the HttpClient it needs no required config, so any page or component can take a Psr\Log\LoggerInterface dependency with zero setup. Two optional env vars tune it:

LOG_LEVEL=info     # threshold; one of the 8 PSR-3 levels. Default: dev=debug, prod=info
LOG_FILE=/var/log/app.log   # sink path. Default: php://stderr

Left unset, log lines go to STDERR (12-factor: docker logs, journald, or a platform log drain collects them). Set LOG_FILE only for deploys that want a file — directory creation, .gitignore and rotation are then yours to manage.

Use it

Take a Psr\Log\LoggerInterface dependency in a page or component constructor:

use Psr\Log\LoggerInterface;

final class CheckoutPage extends PageComponent
{
    public function __construct(private readonly LoggerInterface $log) {}

    public function render(): string
    {
        $this->log->info('checkout started for {user}', ['user' => $userId]);
        // ...
    }
}

{placeholder} interpolation (PSR-3 §1.2) is applied to the sink output. The canonical ['exception' => $e] context key is formatted by Monolog.

What you get for free

Profiler (dev) — every entry is mirrored onto the profiler timeline as a log event whose label is the level, carrying the interpolated message and a redacted copy of the context: values under a pass/pwd/secret/token/api_key/auth key are masked and a Throwable is reduced to Class: message (profiles are plain JSON under var/cache/profiler/ — the same stance TraceableDatabase takes on bound values). The redaction is profiler-only: the real Monolog sink still receives the original context the app chose to log. In prod the alias points straight at Monolog with no decorator, so there is no overhead.

Profiler

A dev-only request profiler. Each request is recorded as a Profile (URL, method, status, event timeline) and inspectable through the /_profiler web view. Zero cost in production — user code can take a Profiler dependency without caring about the environment.

How it works

Profiler::class is always bound in DI:

prod (APP_ENV not dev/development) → NullProfiler. Every method is a no-op, callable without an if profiler enabled branch.
dev (APP_ENV=dev) → RecordingProfiler. Events accumulate on the Profile and are persisted by FileProfilerStorage to <projectRoot>/var/cache/profiler as JSON at end of request.

In dev, the Traceable decorators wrap AppRouter / Database / EtagStore / SessionStorage / Authenticator and feed spans like db.query, cache.etag_*, and session.* into the profile automatically. <X defer /> sub-requests are linked to their parent via parentToken.

Web view

TraceableAppRouter intercepts /_profiler before normal dispatch (so the profiler never profiles itself):

URL	Content
`/_profiler`	Recent requests (defer sub-requests folded into parent)
`/_profiler/<token>`	One request in detail (event timeline + sub-requests)

Pure HTML — no JS, no external CSS — so it works offline.

Instrumenting from code

Take a Profiler in any page/service constructor:

use Polidog\Relayer\Profiler\Profiler;

public function __construct(private readonly Profiler $profiler) {}

// one-shot event
$this->profiler->collect('app', 'cache warmed', ['keys' => 12]);

// timed span (finalized by stop())
$span = $this->profiler->start('app', 'heavy compute');
$result = $this->compute();
$span->stop(['rows' => \count($result)]);

// timed span around a call, finalized for you (returns the call's value,
// records an `error` payload and rethrows if it throws)
$user = $this->profiler->measure('lib', 'sdk.fetchUser',
    fn () => $this->thirdPartySdk->fetchUser($id));

The same calls are no-ops under NullProfiler, so no environment branching is needed.

Tracing your own libraries

To see a third-party SDK or an internal service on the profiler timeline, wrap the call site with measure() — that is the whole feature. It records only the collector/label/duration, never the call's arguments or return value: a generic wrapper can't know which argument is a password or token, so it records nothing it wasn't explicitly given. If you want a payload, use start() + stop() and pass only what is safe.

When you call the same dependency from many places and want every call traced without repeating measure(), write a thin decorator — the same pattern the framework's own Traceable* classes use — and swap it in for dev only from your AppConfigurator:

final class TraceableWeatherApi implements WeatherApi
{
    public function __construct(
        private readonly WeatherApi $inner,
        private readonly Profiler $profiler,
    ) {}

    public function forecast(string $city): Forecast
    {
        // Choose the label/payload deliberately — record the city, not an
        // API key the real client might also take.
        return $this->profiler->measure('lib', 'weather.forecast',
            fn () => $this->inner->forecast($city));
    }
}

// config: AppConfigurator::configure()
if ($_ENV['APP_ENV'] === 'dev') {
    $container->register(TraceableWeatherApi::class)
        ->setArguments([new Reference(HttpWeatherApi::class), new Reference(Profiler::class)])
        ->setPublic(true);
    $container->setAlias(WeatherApi::class, TraceableWeatherApi::class)->setPublic(true);
}

Prod keeps the plain alias, so the decorator and its profiler cost exist only in dev — exactly how TraceableDatabase / TraceableHttpClient are wired. Each decorator stays responsible for its own redaction (log the city, not the key); there is deliberately no generic "trace every service" proxy, because it would strip that per-contract judgement and leak secrets into the dev profile JSON.

Clearing stored profiles

vendor/bin/relayer profiler:clear deletes the JSON profiles under var/cache/profiler so /_profiler starts fresh. It only removes the *.json the storage writes (the directory is recreated on the next dev request); a missing cache is reported and treated as success, so re-running is always safe.

Source Layout

Namespace	Purpose
`Polidog\Relayer\Relayer`	Boot entrypoint (env load + DI build + router wire-up).
`Polidog\Relayer\AppConfigurator`	Extension point for service registrations.
`Polidog\Relayer\InjectorContainer`	PSR-11 adapter with reflection autowire + 304 short-circuit.
`Polidog\Relayer\Router\AppRouter`	File-based router for `src/Pages/` (PSR-11 container–driven).
`Polidog\Relayer\Router\Component\*`	`PageComponent`, `ErrorPageComponent`, `FunctionPage`, `PageContext`.
`Polidog\Relayer\Router\Layout\*`	`LayoutComponent` + nested layout rendering.
`Polidog\Relayer\Router\Document\*`	HTML document wrapper / metadata.
`Polidog\Relayer\Router\Form\*`	CSRF tokens + form action dispatcher.
`Polidog\Relayer\Router\Routing\*`	Page scanner, route table, matcher.
`Polidog\Relayer\Db\Database`	Minimal SQL contract (default: `PdoDatabase`, cached, dev-traced).
`Polidog\Relayer\Db\DatabaseException`	The single error type the DB layer raises.
`Polidog\Relayer\Http\Client\HttpClient`	Minimal HTTP contract (default: `CurlHttpClient`, cached, dev-traced).
`Polidog\Relayer\Http\Client\HttpResponse`	HTTP client result (status / headers / body / json()).
`Polidog\Relayer\Http\Client\HttpClientException`	The single error type the HTTP client layer raises.
`Polidog\Relayer\Http\Cache`	`#[Cache]` attribute.
`Polidog\Relayer\Http\CachePolicy`	Header emission + conditional GET evaluation.
`Polidog\Relayer\Http\EtagStore`	Pluggable ETag storage interface.
`Polidog\Relayer\Http\FileEtagStore`	Default file-backed `EtagStore` implementation.
`Polidog\Relayer\Auth\Auth`	`#[Auth]` attribute.
`Polidog\Relayer\Auth\Authenticator`	Session-based authentication orchestrator.
`Polidog\Relayer\Auth\Identity` / `Credentials`	Principal + login-handshake value objects.
`Polidog\Relayer\Auth\UserProvider`	App-supplied user lookup interface.
`Polidog\Relayer\Auth\PasswordHasher`	Hashing interface (default: `NativePasswordHasher`).
`Polidog\Relayer\Auth\SessionStorage`	Session storage interface (default: `NativeSession`).
`Polidog\Relayer\Validation\Validator`	Zod-style schema builder facade (`safeParse` / `parse`).
`Polidog\Relayer\Validation\Schema`	Schema base + types (string/int/float/bool/enum/array/object).
`Polidog\Relayer\Profiler\Profiler`	Request-tracing facade (dev: recording / prod: no-op).
`Polidog\Relayer\Profiler\ProfilerWebView`	`/_profiler` dev view (index + detail).

The only third-party runtime dependency is polidog/use-php (the JSX-style component runtime). DI, dotenv, and Symfony YAML config are all wired by Relayer::boot() — there is no other package to install.

Running Tests

vendor/bin/phpunit

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 138 Commits
.claude		.claude
.github/workflows		.github/workflows
bin		bin
example		example
src		src
tests		tests
.gitignore		.gitignore
.php-cs-fixer.dist.php		.php-cs-fixer.dist.php
CLAUDE.md		CLAUDE.md
README.ja.md		README.ja.md
README.md		README.md
composer.json		composer.json
mise.toml		mise.toml
phpstan.neon		phpstan.neon
phpunit.xml		phpunit.xml

Folders and files

Latest commit

History

Repository files navigation

Relayer

Requirements

Installation

Scaffold a new project

Upgrading the project structure

Project Layout

Quick Start

Environment Variables

Routing & Pages

Class-style page

Function-style page

Layouts

Error pages

Control flow: redirect() / notFound() / abort()

API Routes

Per-page scripts ($ctx->js() / addJs())

React Islands (rich-UI escape hatch)

Middleware

Inspecting routes

Server Actions (form / CSRF-protected)

Class-style: PageComponent::action()

Function-style: PageContext::action()

Binding arguments

Re-rendering after a failed submit

Service Registration

Option A — config/services.yaml (auto-loaded)

Option B — AppConfigurator (PHP)

Autowire defaults

Injecting Services Into Pages

Accessing the HTTP Request

Authentication

1. Implement a UserProvider

2. Bind the provider

3. Log users in

4. Protect pages

Class-style: #[Auth]

Function-style: $ctx->requireAuth() / Identity injection

5. Pluggable parts

Notes

6. Token authentication (Firebase / Cognito)

Bind a TokenVerifier

Mode A — stateless API (bearer per request)

Mode B — session login (verify once, then a cookie session)

Precedence (one rule, no hybrid)

Notes

HTTP Cache Headers via #[Cache]

Conditional GET / 304 Not Modified

Example

Function-style pages: $ctx->cache()

Dynamic ETag via EtagStore

Default backend: FileEtagStore

Custom backend (e.g. Redis)

Notes / caveats

Database

Enable it

Use it

What you get for free

Fetching external APIs (HTTP client)

Enable it

Use it

What you get for free

Validation

Declaring a schema

Parsing

With form actions

Internationalization (i18n)

Configure

Locale resolution order

Translating your own content

Localized framework messages

Logger

Enable it

Use it

What you get for free

Profiler

How it works

Control flow: `redirect()` / `notFound()` / `abort()`

Per-page scripts (`$ctx->js()` / `addJs()`)

Class-style: `PageComponent::action()`

Function-style: `PageContext::action()`

Option A — `config/services.yaml` (auto-loaded)

Option B — `AppConfigurator` (PHP)

1. Implement a `UserProvider`

Class-style: `#[Auth]`

Function-style: `$ctx->requireAuth()` / `Identity` injection

Bind a `TokenVerifier`

HTTP Cache Headers via `#[Cache]`

Conditional GET / `304 Not Modified`

Function-style pages: `$ctx->cache()`

Dynamic ETag via `EtagStore`

Default backend: `FileEtagStore`

Packages