Relayer
English · 日本語
Opinionated, batteries-included framework on top of
polidog/rosanna and
polidog/rosanna-defer. 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
- Native route handlers in Go (
src/Pages/.../route.go, func GET(w, r)
and friends) — compiled by relayer native:build, run per request as a
CGI process via the Go stdlib; the Next.js "native language support"
prototype's Route Handlers, for CPU-heavy endpoints — and its Proxy:
src/Pages/middleware.go with a func Proxy(w, r) as the root
middleware, continuing via a Relayer-Next header
- 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 ready-made Cors, OriginGuard (reject requests that
bypass your CDN) and TrustedProxy (real client IP behind a proxy)
middlewares — the latter two wired from .env (ORIGIN_SECRET,
TRUSTED_PROXIES) as a router guard that runs before everything
- 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/rosanna-defer.js, which the default document references on every page.
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 rosanna-defer asset-publish scripts, and an
extra.relayer.structure_version marker, and leaves everything else
untouched;
.env.local (APP_ENV=dev) is written only into a new project: one with
no .env, no marker, and none of src/Pages, src/AppConfigurator.php,
public/index.php or public/worker.php. An existing app keeps its
environment, and init tells you how to add dev mode yourself.
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
This is the beginning of the README. Read the rest at the original. Read the full README ↗
