Getting Started#

Relayer is an opinionated, convention-first PHP full-stack framework built on top of polidog/rosanna and polidog/rosanna-defer. With conventions in the style of the Next.js App Router, it brings file-based routing, JSON APIs, server actions, authentication, validation, caching, and the DB together into a single boot entry.

Requirements#

• PHP 8.5 or later
• Composer
• polidog/rosanna, polidog/rosanna-defer, and Symfony's DI / Config / YAML / Dotenv (composer require installs them automatically)

Installation#

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

vendor/bin/relayer init generates scaffolds such as public/index.php, src/Pages/, config/services.yaml, and .env (it does not touch existing files). In a new project it also writes APP_ENV=dev to the gitignored .env.local, so the app runs in dev mode right away.

init also generates a full set of FrankenPHP development containers (Dockerfile, php.ini, compose.yaml, .dockerignore). You can start it without installing PHP on the host.

docker compose up --build   # → http://localhost:8000

compose.yaml is a minimal setup with only the app service (mounting the source and the MySQL db service are scaffolded as comments). The dev target of the Dockerfile sets APP_ENV=dev, so .psx is compiled on the fly inside the container = no build step. For production, the prod target runs vendor/bin/relayer compile ahead of time (see Deployment).

Entry point#

The whole app boots from this one file (public/index.php).

<?php
declare(strict_types=1);

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

use Polidog\Relayer\Relayer;

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

Relayer::boot() loads .env, builds the Symfony DI container, and returns an AppRouter. You can add settings such as addCssPath() until you call ->run().

Your first page#

src/Pages/page.psx is the top page (/). .psx is PHP that lets you write JSX-style syntax, which Rosanna compiles.

<?php
declare(strict_types=1);

use Polidog\Rosanna\Html\H;

return fn () => (
    <section>
        <h1>It works</h1>
        <p>Edit src/Pages/page.psx.</p>
    </section>
);

Carving out a directory makes it a URL segment, and an [id] directory is a dynamic segment. For details, see Routing & Pages.

About this site#

This documentation site itself is built with Relayer. The content is held in Turso (libSQL) as the single source of truth, and is edited directly with $EDITOR from the bin/docs CLI (there are no intermediate Markdown files). On the server side, Relayer handles display and full-text search. For how it works, see Deployment.

Development and production#

APP_ENV=dev enables on-the-fly PSX compilation, the profiler, and tracing. Any other value, or none, is treated as production, and you precompile at deploy time with vendor/bin/relayer compile. The committed .env does not set APP_ENV; enable dev mode in the gitignored .env.local. After cloning, run echo APP_ENV=dev >> .env.local (see Environment Variables).