Getting Started#

Relayer is an opinionated, convention-first PHP full-stack framework built on top of polidog/use-php. 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/use-php, 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).

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 default .env is APP_ENV=dev, so .psx is compiled on the fly inside the container = no build step. For production, with this image you remove APP_ENV and run vendor/bin/usephp compile src/Pages 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 use-php compiles.

<?php
declare(strict_types=1);

use Polidog\UsePhp\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 in .env enables on-the-fly PSX compilation, the profiler, and tracing. Anything else (including unset) is treated as production, and you precompile at deploy time with vendor/bin/usephp compile src/Pages.