Download the PHP package polidog/relayer without Composer

On this page you can find all versions of the php package polidog/relayer. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package relayer

Relayer

日本語

Opinionated, batteries-included framework on top of polidog/rosanna and polidog/rosanna-defer. Bundles:

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

Requirements

Installation

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 install (rather than dump-autoload) so the App\ autoload and the publish scripts init just added both apply — the latter emits public/rosanna-defer.js, which the default document references on every page.

It is idempotent and non-destructive:

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:

It reads the extra.relayer.structure_version marker, applies the deltas between it and the current one, then advances the marker (the one mutation init deliberately never makes). New files are skip-if-exists, so a file you have edited is kept and reported as skipped (=).

A version can also change the content of a file it shipped earlier — the Dockerfile gaining a production target, say. Those are reported separately and gated on the file being untouched: upgrade replaces your copy only when it is still byte-for-byte what some framework version wrote (~). If you have edited it at all, it is left exactly as it is and listed as kept (!), with a note that the template moved on; take the new one by saving your changes, deleting the file and running relayer init. So the command can update a stale template without ever overwriting your work.

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

Quick Start

public/index.php:

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

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

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

The default document loads rosanna-defer.js on every page. To load it only on pages that rendered a defer placeholder, opt in:

A page without a placeholder then has no window.Rosanna. A logout form on such a page cannot call clearDeferCache(), so a user-specific localCache fragment survives logout and a shared device can show it to the next user. Use the option only if no page without a placeholder needs window.Rosanna.

Environment Variables

Put a .env in the project root:

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:

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

Missing files are skipped silently. Variables already in $_ENV / $_SERVER / getenv() (real environment variables) win over every one of these files, .local included; among the files, the .local ones override the committed counterparts.

APP_ENV=dev (or development) enables PSX auto-compilation. Any other value treats the app as production, as does APP_ENV being set nowhere: neither in the real environment nor in any of these files. For a new project, relayer init writes APP_ENV=dev to the gitignored .env.local, so a deploy that forgets it runs as production; after a fresh clone, run echo APP_ENV=dev >> .env.local. In production, pre-compile with vendor/bin/rosanna-defer 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 / 405 / $ctx->abort() / auth 401+403 / uncaught exceptions (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/rosanna-defer 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.

Compiled DI container (production). Otherwise Relayer::boot() builds and compile()s the Symfony DI container on every request — typically the largest avoidable per-request cost. vendor/bin/relayer container:compile dumps it to a plain PHP class at var/cache/container/CompiledContainer.php; production requires that instead of rebuilding. Same presence-gated, dev-excluded contract as compiled routes (no file ⇒ live build; dev always reflects current config). A bad service definition fails the dump at deploy, not on the first request.

Deploy checklist. Build the three artifacts and ship an OPcache-warm, scan-free image:

relayer compile is shorthand for the three standalone steps, which you can still run individually (e.g. to skip container:compile — see "Runtime secrets" below):

Then set APP_ENV=prod, in .env.local or as a real environment variable, and run with OPcache validate_timestamps=0 (the scaffolded php.ini carries the production block). Make sure no .env.local with APP_ENV=dev reaches the server: it exposes /_profiler. Each step is presence-gated, so a missing artifact degrades to the live path rather than breaking.

relayer compile deliberately does not include vendor/bin/relayer native:build (Go route handlers, see Native route handlers (Go)): it needs a Go toolchain, which a PHP-only image has no reason to carry. Run it as its own step when the project has a route.go.

Read-only filesystem. The scaffolded Dockerfile runs all three steps in its prod target, so the image generates nothing at runtime and can be served with an immutable filesystem. compose.yaml ships that shape as a commented app-prod service: read_only: true plus a small tmpfs on each path still written — the ETag store (var/cache/etags), PHP sessions and upload temp files (both relocated under var/cache/ by the prod image), and Caddy's own /data + /config (the FrankenPHP image points XDG_DATA_HOME / XDG_CONFIG_HOME there and declares no VOLUME, so a read-only container cannot start without them). Do not mount over var/cache/ as a whole: the compiled routes, container and .psx are built into the image, and an empty tmpfs on top hides them — every request then silently falls back to the per-request scan and rebuild the artifacts exist to remove.

Runtime secrets vs container:compile. container:compile runs AppConfigurator::configure() once, at deploy, and bakes whatever value the configurator passes to setParameter() into the dumped class. Production boot only requires the dump — the configurator never re-runs. So code that reads env vars directly and hands the resolved string to the container will freeze whatever value the env had at compile time:

Under deployments that inject secrets only at boot (Fly secrets, Cloud Run env, sidecar injectors, …), the build environment legitimately has those vars unset, so the dump ships with empty strings — and downstream "is this configured?" checks silently take their fallback branch in production.

Use Symfony DI's %env(VAR)% placeholder instead. PhpDumper emits it as a getEnv('VAR') call in the dumped class, so the value resolves at load time against the live env:

Typed / fallback resolution is available via %env(int:DB_PORT)%, %env(bool:FEATURE_FLAG)%, %env(default::API_TOKEN)%, etc. The same placeholders work in config/services.yaml (the bundled Polidog\Relayer\Auth\Token\TokenVerifier example already uses them).

routes:compile is unaffected — it only scans src/Pages/ and reads no env. Only container:compile carries the env coupling. If a deployment model can't accommodate the %env(...)% rewrite, dropping container:compile while keeping routes:compile and accepting the per-request ContainerBuilder::compile() cost is a valid fallback.

Class-style page

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.

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

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:

Error pages

A root error.psx renders error responses inside the root layout — an unmatched route (404), an unsupported method on a page (405), every $ctx->abort() status, the 401 / 403 from #[Auth] / $ctx->requireAuth(), the 403 of a form action refused for its CSRF token or signature, and an uncaught exception (500). If the root layout itself fails an auth guard or aborts while rendering the error, error.psx renders without it; if error.psx fails the same way, the default document is used. The status is unchanged either way. It receives the status and message, so one error.psx can branch on the status for a 404 vs. 403 vs. 500 page — don't hard-code "not found" wording in it. Without one, the framework emits a minimal default document.

Write it function-style, like a page, or as a class extending ErrorPageComponent:

The function's parameters are filled by type: array gets the props ['status' => int, 'message' => string], int the status, string the message, Request the request, and any other class a container service. It may return the Element or, like a page factory, a render closure.

An error.psx that is neither (it returns no closure and declares no Renderable class, or its closure can't be wired) is a configuration error: in dev it is thrown, so the debug page says what is wrong; otherwise it is logged as a warning (and recorded on the profiler) and the default document answers with the same status.

Uncaught exceptions

Anything thrown by a page, layout, deferred component, route.php/route.go dispatch or middleware.php that nothing else handles becomes a 500. The control-flow exceptions (abort(), notFound(), redirect(), requireAuth()) are not affected.

APP_ENV=dev Otherwise
Page Built-in page with the stack trace (error.psx is not used) error.psx with the generic message, or the default document
route.php / route.go {"error": "...", "exception": {class, message, file, line, trace}} {"error": "Internal Server Error"}

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.

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.

Native route handlers (Go)

A route.go is an API route written in Go — the same URL mapping as route.php, with the handler compiled to a native binary. This mirrors the Next.js "native language support" prototype (Route Handlers in Go, for CPU-heavy work beside the app): declare func GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS with the stdlib's http.HandlerFunc signature, nothing else — no main(), no framework import.

Build. vendor/bin/relayer native:build compiles every route.go under src/Pages (and a root middleware.go, see Writing it in Go). For each one it generates the entrypoint (a main() that serves one request through Go's net/http/cgi and switches on the method), copies both into var/cache/native/build/<slug>/ with a stdlib-only go.mod (a go.mod / go.sum you place beside the route.go is used instead, so third-party modules work), and runs go build -o var/cache/native/bin/<slug>. <slug> is the URL pattern with / → __ (/api/users/[id] → api__users__[id]); two routes that end up with one slug (/a/b and /a__b) fail the build. Only route.go and go.mod / go.sum are copied, so a sibling helper.go is not compiled: keep a route in one file, or import shared code as a module. It needs go on PATH — or GO_BIN=/path/to/go — and is a separate command from relayer compile for that reason. A route.go that declares no handler, or is not package main, fails the build with a message naming the file; a compile error prints go build's output verbatim. Output is one line per route:

Nothing is rebuilt at request time, ever. An unbuilt route answers a JSON 500 whose body says to run native:build; in dev (APP_ENV=dev) a binary older than its route.go gets the same answer with (route.go is newer than the binary) appended, so an edit you forgot to rebuild cannot masquerade as a bug. Production serves whatever the deploy built. var/cache/native/ is covered by the scaffolded .gitignore (/var/).

The scaffolded Dockerfile has no Go and does not run native:build, and .dockerignore excludes /var/, so a production image built from it serves every route.go as the unbuilt 500. Add a build stage with Go that runs native:build, then copy var/cache/native/bin into the final image.

How a request runs. There is no resident Go server: PHP starts the binary per request as a CGI child (proc_open), passes the request as CGI meta-variables, streams the body to its stdin and reads a CGI response (Status: / headers / blank line / body) back from stdout. A static Go binary starts in about a millisecond, so the overhead is in the low single-digit milliseconds per call — fine for an endpoint that then does real work, not a replacement for a hot PHP route that returns in 200 µs. Specifically, the handler sees:

Methods. The generated entrypoint applies the route.php rules: an undeclared OPTIONS → 204 + Allow; an undeclared HEAD with a GET → runs GET and drops the body; any other undeclared method → 405 + Allow with a JSON body. Declaring HEAD / OPTIONS yourself always wins. relayer routes lists the declared methods (a text scan of the route.go, so it works before anything is built) in a native row.

Failures are JSON. A non-zero exit (a Go panic included), output that is not a CGI response, or a run longer than the timeout answers a JSON 500 ({"error": "Native route /api/hello failed: …"}), never the HTML error page — like route.php, a native route is an endpoint. What the process wrote to stderr is logged at error through the PSR-3 logger when one is configured (and at warning after a successful run — that is where Go's log package writes). The timeout defaults to 30 seconds; NATIVE_ROUTE_TIMEOUT=10 (seconds) in .env changes it. A PHP with proc_open in disable_functions cannot run native routes and says so at dispatch.

What does not apply. A route.go gets no autowiring, no PageContext, no Request object and no #[Auth] / requireAuth() — the Go side only ever sees CGI variables. Protect it from the root middleware — src/Pages/middleware.php, or its Go form middleware.go — which wraps native routes exactly like pages and route.php (a middleware that does not call $next means the Go process is never started). _private folders exclude a route.go as they do everything else, and a directory holds one handler: route.go beside route.php or a page file is a scan error, like page.psx beside page.php. Go is the only language today; the route kind is deliberately language-neutral so a route.rs could join without touching the router.

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:

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

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.

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:

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

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, …):

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

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).

Writing it in Go (middleware.go)

The root middleware can be Go instead of PHP — the "Proxy in Go" half of the Next.js native-language prototype. src/Pages/middleware.go is package main with a single func Proxy(w http.ResponseWriter, r *http.Request) (named like Next.js's proxy(); no main(), no framework import), built by the same vendor/bin/relayer native:build as route.go to var/cache/native/bin/middleware and started per request before route matching, like middleware.php.

CGI has no "continue to the next handler", so the Go side says what happens through response headers:

Origin guard and trusted proxy (running behind a CDN)

Two more provided middlewares cover the pair of chores every app behind Cloudflare / a reverse proxy otherwise hand-writes: refuse requests that bypassed the CDN and recover the real client IP. Both are plain fn(Request, $next) closures like Cors.

The framework wires them from the environment. Like DATABASE_DSN auto-wires the Db layer, Relayer::boot() reads these variables and installs the result as the router guard — the hook that runs before everything (the deferred-component endpoint /_defer/{name}, the dev profiler and middleware.php). Nothing set, nothing installed:

Don't put an origin guard in middleware.php: that wraps route dispatch only and is bypassed by the defer / profiler endpoints, so it could be sidestepped by requesting /_defer/{name} directly. To compose your own, AppRouter::setGuard() takes the same fn(Request, $next) closure and replaces what the environment produced:

OriginGuard checks a secret header the CDN stamps on every forwarded request and answers 403 when it is missing or wrong:

TrustedProxy resolves the client IP from a forwarding header, but only when the immediate hop (REMOTE_ADDR) is a proxy you trust. The result is $request->clientIp(); $request->ip() is unchanged and keeps returning REMOTE_ADDR, and clientIp() falls back to ip() when nothing was resolved, so pages can call it unconditionally.

Several proxies in a row (chain). Behind Cloudflare → Fly the hop is Fly, Fly-Client-IP is Cloudflare's address (per Fly's request headers), and the user is in CF-Connecting-IP. A single preset would hand you Cloudflare's IP — per-user rate limits would collapse onto Cloudflare's edge addresses. List the layers outermost-last; each applies only if the address resolved so far is one of that layer's proxies, and the last address that could be verified is the client:

A request straight to xxx.fly.dev resolves to the caller's own address (the Fly layer applies, the Cloudflare layer does not), and a forged CF-Connecting-IP from a non-Cloudflare source is ignored.

Recipe: Cloudflare in front of Fly.io.

  1. Cloudflare → Rules → Transform Rules → Modify Request Header: set X-Origin-Secret to a long random value for your zone.
  2. Hand the app the secret and the trust chain — no PHP involved:

    Rotate by setting the new ORIGIN_SECRET plus ORIGIN_SECRET_PREVIOUS=<old>, then dropping the latter. Relayer::boot() installs the fly → cloudflare TrustedProxy chain outside OriginGuard as the router guard — so /_defer/* and the profiler are covered too, and a rejected direct hit is logged with its real source IP rather than the Fly proxy's address.

  3. Verify: curl -I https://<app>.fly.dev/ is 403, the custom domain (through Cloudflare) is 200, and /healthz is 200 either way.

Cors stays in src/Pages/middleware.php as before. The example/ app runs unguarded until you set these in its .env.local.

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:

Pages report GET,POST (POST is how server actions reach a page). HEAD and OPTIONS are not listed, as for route.php: a page answers HEAD like GET without a body, and OPTIONS with 204 + Allow: GET, HEAD, OPTIONS, POST without running page code. Any other method gets 405 + Allow: GET, HEAD, POST, rendered by error.psx. Both are decided after the root middleware, so a CORS preflight is still answered by Cors::middleware(). API routes list their declared methods, and native routes (route.go) the func GET & co. found by a text scan — no build needed. A route.php that fails to load, or a route.go that declares no handler, is shown as ? with a warning line, not silently hidden. The trailing line names the root middleware when there is one — (php) for middleware.php, (native) for middleware.go.

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 signed action token. Put it in the <form>'s action attribute: the framework turns that form into a POST back to the current URL and adds the _rosanna_action and _rosanna_csrf hidden fields itself. Submitting the form invokes the matching method on the page before render():

Invalid CSRF tokens return a 403, rendered through the same error path as $ctx->abort(403) (error.psx, or the built-in page) — the page itself is not rendered. Don't write the token into a _rosanna_action hidden input yourself: only a form whose action holds the token gets the _rosanna_csrf field, so such a form is always refused with 403.

A class-style page has no PageContext, so redirect by throwing RedirectException (what $ctx->redirect() throws). The router turns it into a Location response — 303 See Other by default.

Only methods the page class itself declares can be actions: passing an inherited framework method (or anything other than [$this, 'method']) to action() throws, and the dispatcher only runs a method named by a token the server signed (see Binding arguments) — a hand-crafted token naming some other public/protected method is ignored.

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):

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

Actions can also be registered outside the factory, e.g. from a Renderable child's render() via PageContext::current()->action() — a child of the page or of a layout. On a POST that submits such an action, the render closure, the layouts around it and every Renderable child in the tree (inside arrays, nested elements and defer fallbacks too) render once before dispatch so the action is registered, and again after dispatch for the response. A GET, or a POST to an action the factory registered, renders once. Metadata and scripts the factory declared are kept for the response; ones declared while rendering are declared again by the second render, not twice.

The response render runs the render closure again, so its children are new objects built with the props of that render (a list the action added to shows the new item). State the action kept on the child's $this is carried over: every property the action changed on a child of the first render is copied onto the child of the same class at the same place in the new tree before it renders. Readonly properties count as props and are never copied, and a property the action did not change keeps the new child's value. So a form child can hold its own validation errors:

"The same place" is the position in the tree, as React keeps state by type and position: if the action changes which children come before the form (say, a new list item rendered as its own child ahead of it), the state lands on whichever child of that class is now there. Assign the property ($this->errors = ..., $this->errors[] = ...) rather than mutating an object it holds — a change inside such an object is not detected. State the page itself needs, or state that must survive such a reshuffle, belongs in the factory, captured by reference (see Re-rendering after a failed submit).

Binding arguments

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

The action token (target page/class + action name/method + $args) is HMAC-signed with a random per-session key kept in $_SESSION (next to the CSRF token) and verified before dispatch. A token whose target or $args were edited client-side — or one minted for another session — is rejected with a 403 and the handler never runs. POSTed fields only ever reach the first (form data) argument, so a form field named like a bound argument cannot override it. $args is signed, not encrypted — it is readable in the page source, so don't bind secrets; and still authorize inside the handler (a valid token proves the server bound the value, not that the current user may act on it).

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):

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.php (returning a ContainerConfigurator closure) and config/services.yml are also accepted.

Per-environment overrides

Two complementary mechanisms let you vary config by env — both resolve <env> to dev (when APP_ENV=dev or APP_ENV=development) or prod (everything else).

when@<env> blocks inside services.yaml — Symfony's standard in-file env override:

Sibling services.{env}.yaml / .yml — a dedicated per-env file loaded after the base; useful when the env-specific section would otherwise dominate the file:

Both forms also work for services.php / services.{env}.php. Precedence (lowest → highest): framework defaults → services.{yaml,yml,php} (incl. when@<env>) → services.{env}.{yaml,yml,php} → AppConfigurator.

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:

Then pass it to boot():

PSX components — accessing services

PSX component files (.psx) are plain closures, so constructor injection is unavailable. Use Relayer::container() to pull a service from the DI container directly inside a component:

Relayer::container() returns the same PSR-11 container boot() built. It throws \LogicException if called before boot(). For regular services (page handlers, route classes) prefer constructor injection via AppConfigurator — this accessor is an escape hatch specifically for the PSX component context where closures make injection impractical.

A deferred component that throws still answers its /_defer/{name} fetch with a bare 500, but the failure now also goes to the container's LoggerInterface (and the dev profiler), not only to PHP's error log.

Components get their arguments from the container, so RosannaDefer::setArgumentResolver() does not apply to them. Code that calls PsxComponentRegistrar::configure() without a container can pass its own resolver as argumentResolver:.

Autowire defaults

The framework iterates every Definition you register and:

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:

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

A registered page, layout or error page is still built anew for every request: the container makes a non-shared service of each class declared in a page, layout or error file under src/Pages (including one that only implements Renderable) and of each class that extends PageComponent or ErrorPageComponent, or implements LayoutInterface, even if you call setShared(true) on it, and the compiled container (relayer container:compile) does the same. Other Renderable services, such as components, stay shared. So an object the page creates in its constructor (a form, a DTO) never carries one visitor's state to the next on a long-running worker, while the services injected into it are still the container's shared ones. The router renders such a new object as it is, so a page or layout does not have to be cloneable.

An object handed to the container with set() cannot be rebuilt; the router renders a shallow clone of it, so objects it holds are shared between requests, and a class that cannot be cloned (a private __clone()) fails the request with a RuntimeException. Don't register pages that way.

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.

Request API (all immutable):

Method Returns
$req->method uppercase HTTP method
$req->path request path (no query string), percent-encoded in one canonical spelling
$req->decodedPath() $req->path decoded, for comparing (e.g. /日本語)
$req->uri() verbatim request URI (query string included)
$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)
$req->body() raw request body (php://input, read lazily)
$req->json() ?array — body as JSON, null if absent/invalid
$req->file($name) ?UploadedFile (null for a name[] field)
$req->files() array<string, UploadedFile\|list<UploadedFile>>
$req->ip() ?string — REMOTE_ADDR as reported
$req->clientIp() ?string — resolved by TrustedProxy, else ip()
$req->host() / scheme() ?string / 'http'\|'https'
$req->url() ?string — absolute URL of this request

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

You never need a superglobal. $_GET / $_POST / $_SERVER / $_FILES / php://input are all reachable through the injected Request, including from a <X defer /> fragment — deferred components are autowired from the container exactly like pages, so they take Request, Authenticator, or any bound service by type:

A JSON API route and an upload, end to end:

UploadedFile carries clientName, clientMimeType, size, tmpName, error, plus isValid(), contents(), and moveTo() (which refuses anything that isn't a real upload). ip() reports REMOTE_ADDR only — X-Forwarded-For is client-supplied. Behind a proxy you trust, wire TrustedProxy (see the Middleware section) and read clientIp(), which falls back to ip() when nothing was resolved.

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.

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:

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.

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.

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=<original-path-and-query> (URL-encoded, same-origin only): GET /boards/1?x=1&y=2 redirects to /login?next=%2Fboards%2F1%3Fx%3D1%26y%3D2. A request under a /{locale} prefix keeps it on both ends: GET /ja/boards redirects to /ja/login?next=%2Fja%2Fboards. Authenticated users lacking the required role get 403 Forbidden. Both 401 and 403 render error.psx (or the default error document).

#[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:

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):

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:

NativeSession starts the session lazily, so just resolving the service through DI does not eagerly emit Set-Cookie. Only a write creates a session: on a request without a session cookie, reads see an empty store and start nothing, so an anonymous visitor to a page that merely checks $auth->user() gets no Set-Cookie and stays CDN-cacheable. It shares $_SESSION with the existing CSRF token machinery — no duplicate session starts.

The session cookie gets HttpOnly, SameSite=Lax, and Secure when $_SERVER['HTTPS'] says the request came over TLS. Behind a proxy that terminates TLS, set session.cookie_secure=1 or pass HTTPS=on to PHP; X-Forwarded-Proto is not consulted. Only attributes left at PHP's default are filled in, so your own values win: anything session_set_cookie_params() set before the session starts (SameSite=Strict, lifetime, path, domain), and php.ini / -d values including an explicit session.cookie_httponly=0 (spell it 0: PHP parses Off as blank, the same as a stock php.ini). A runtime httponly => false looks like the default, so to turn the cookie defaults off altogether call this before run():

Notes

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:

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:

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:

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

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.

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:

  1. cache validation headers (ETag, Last-Modified, Cache-Control, Vary) are emitted
  2. status is set to 304 Not Modified
  3. 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.

A request with a session cookie or an Authorization header always renders and never gets a 304, and so does one that has started a session by the time the policy is evaluated (a middleware.php that logged the visitor in from a remember-me cookie), even if it closed the session again with session_write_close() before calling $next(). A validator says nothing about who is asking, so a browser that cached the page anonymously would otherwise keep that copy after logging in.

A response to a request carrying an Authorization header is never left storable by a shared cache either: any policy other than private or noStore goes out as Cache-Control: private, no-store, on class and function pages alike. This also covers a header a middleware added with $request->withHeader() and the REDIRECT_HTTP_AUTHORIZATION copy Apache/CGI hands over, which Request reads as authorization when the real header is missing. A session cookie on its own does not count: a page that never touches the session keeps its declared policy (see the session note below).

Example

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

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

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:

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:

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:

Then wire it through services.yaml:

…or in AppConfigurator::configure():

Notes / caveats

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 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:

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

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

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:

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

Use it

Take an HttpClient dependency in a page or component constructor:

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).

What you get for free

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:

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
satisfies($judge, $cond, $msg, $t) Semantic check via a Judge (see below)

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

Parsing

With form actions

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

Semantic checks (TypeSafe Jev)

satisfies($judge, $condition, $message, $threshold = 0.5) validates what code can't — "is this spam?", "is this a real support question?". The value is sent to a Judge as state {"value": …}; the field passes when the condition holds with probability >= $threshold.

Set TYPESAFE_API_KEY (optionally TYPESAFE_MODEL, default jev-latest) and Polidog\Relayer\Validation\Judge is bound to JevJudge, which asks TypeSafe's Jev a noul question via the HttpClient. Without the key Judge is not registered.

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

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:

  1. 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.
  2. 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.
  3. Cookie — LOCALE_COOKIE (CDN-safe; no session). Set it from a route.php handler with Response::withCookie(), e.g. ->withCookie('locale', 'ja', ['expires' => new DateTimeImmutable('+1 year')]).
  4. Accept-Language — q-value negotiated against the supported list.
  5. 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 (Rosanna 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:

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

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:

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:

{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

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:

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. Notices Rosanna raises while rendering (an attribute it drops) are recorded as rosanna.notice / rosanna.warning, then passed on to your error handler. <X defer /> sub-requests are linked to their parent via parentToken.

Web view

AppRouter intercepts /_profiler before normal dispatch (when a ProfilerStorage has been wired in via setProfiler() — dev only) — 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:

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:

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 component runtime is polidog/rosanna (JSX-style rendering and the PSX compiler) and polidog/rosanna-defer (deferred fragments). DI, dotenv, and Symfony YAML config are all wired by Relayer::boot() — there is no other package to install.

Migrating from polidog/use-php

Relayer now runs on polidog/rosanna and polidog/rosanna-defer.

useState and everything built on it are gone: useState, useFormAction, fc(), onClick / onChange / onInput / onSubmit, wire:*, Snapshot storage and partial page updates. Rendering an event prop now throws an exception. Use a server action ($ctx->action()) or a React island instead. USEPHP_SNAPSHOT_SECRET is no longer read, and AppRouter::setUsePhp() is now setRosanna().

  1. Run vendor/bin/relayer upgrade. It replaces the asset publisher in your composer.json scripts, and updates scaffolded files you have not edited.
  2. In your .psx and PHP files, change Polidog\UsePhp\Html\H, Polidog\UsePhp\Runtime\Element and the like to Polidog\Rosanna\….
  3. Replace fc(fn, defer: new Defer(...)) with deferred(fn, new Defer(...)). Defer is now Polidog\Rosanna\Defer\Defer and the function is Polidog\Rosanna\Defer\deferred.
  4. Replace window.usePHP with window.Rosanna, the X-UsePHP-Defer header with X-Rosanna-Defer, and data-usephp-* with data-rosanna-* in your own JS and templates. If you read the form fields directly, _usephp_action and _usephp_csrf are now _rosanna_action and _rosanna_csrf.
  5. Precompile with vendor/bin/relayer compile. vendor/bin/usephp compile no longer exists, and vendor/bin/rosanna compile does not write the deferred manifest Relayer needs.

  6. The committed .env no longer sets APP_ENV=dev, and a .env without APP_ENV now means production. When relayer upgrade rewrites an untouched .env, it moves APP_ENV=dev to the gitignored .env.local: it creates the file, appends the line if the file does not set APP_ENV, and leaves a file that does set it alone. An edited .env stays as it is and no .env.local is written, whatever it says, so check APP_ENV yourself. relayer init writes .env.local only in a new project. Other checkouts need echo APP_ENV=dev >> .env.local. Both commands first make sure .gitignore excludes .env.local, and write nothing if they cannot. If Git tracks .env.local, .gitignore does not help: upgrade then leaves .env and .env.local as they are and fails (init skips the file). Run git rm --cached .env.local, commit, and re-run relayer upgrade.
  7. The <div data-rosanna="…"> that wrapped the page is gone. Fix any CSS or JS that relies on it.
  8. The scaffolded Caddyfile now really sends requests to public/worker.php (the old worker block was never reached), so relayer upgrade turns worker mode on if you have not edited the file. It is for production: the single binary or frankenphp run --config Caddyfile. Develop with php -S 127.0.0.1:8000 -t public or docker compose up --build, which serve each request from scratch and do not read it. In a worker, container services live across requests, so your own services must not keep per-request state in properties. Clear what they do hold after each request with RequestLifecycle::onReset() (one callback per name; the same name replaces it):

    To stay in classic (per-request) mode, remove the index and worker lines from the Caddyfile.

Rosanna renders some props differently from React. Pass style as a string (style="color: red"); an array is dropped. key is not special: <li key="1"> renders as is. There is no raw HTML injection: dangerouslySetInnerHTML is dropped like any other non-scalar attribute. Rosanna reports each dropped attribute with an E_USER_NOTICE, and in dev the profiler records it as a rosanna event.

Forms rendered by the previous version stop working when you deploy, because the field names and the session keys changed. Purge your CDN at deploy time so it does not serve old HTML or the old usephp.js.

Running Tests

License

MIT


All versions of relayer with dependencies

PHP Build Version
Package Version
Requires php Version >=8.5
ext-curl Version *
ext-openssl Version *
firebase/php-jwt Version ^7.0
polidog/rosanna Version ^1.0
polidog/rosanna-defer Version ^1.0
symfony/dependency-injection Version ^7.1
symfony/config Version ^7.1
symfony/yaml Version ^7.1
psr/container Version ^2.0
symfony/dotenv Version ^7.1
monolog/monolog Version ^3.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package polidog/relayer contains the following files

Loading the files please wait ...