CLI コマンド#

composer require polidog/relayer を入れると 2 つの実行可能ファイルが vendor/bin/ に入ります。

relayer#

引数なし／-h／--help／help で使い方を表示します（引数なしは終了コード 2、明示ヘルプは 0）。未知のコマンドは使い方を出して 2。

vendor/bin/relayer            # 使い方（exit 2）
vendor/bin/relayer --help     # 使い方（exit 0）

relayer init#

カレントディレクトリにプロジェクト構成をスキャフォルドします。 composer require polidog/relayer 済みのディレクトリで実行します。

• 既存ファイルは 触りません。composer.json は追記的にパッチ

され、extra.relayer.structure_version が刻まれます（手で編集しない）。init はこのマーカーを進めず、どの構造で生成されたかを常に判別できるようにします。前進は relayer upgrade の仕事です（下記）。

• 生成物に FrankenPHP の開発用コンテナ（Dockerfile・php.ini・

compose.yaml・.dockerignore）が含まれます。ホスト PHP 無しで docker compose up --build 起動（→ はじめに）。

• AI エージェント向け規約ファイルも生成します。RELAYER.md

（ルーティング / Response 契約 / CSRF / 設計方針の唯一の正）と、それを指すだけの 2 行 AGENTS.md / CLAUDE.md（エージェントツールと Claude Code がそれぞれ自動で読むファイル名）。 polidog/relayer に同梱されフレームワークと co-version され、 skip-if-exists（利用者の既存ファイルを上書きしない）。

• .claude/ 配下に Claude Code 向けツールも生成します — トリガー

時にルーティング /Response/ CSRF 契約を渡す relayer-routing skill （.claude/skills/relayer-routing/SKILL.md）と、変更を RELAYER.md に照らしてレビューする relayer-reviewer subagent（.claude/agents/relayer-reviewer.md）。いずれも RELAYER.md を唯一の正とし、同じく co-version・skip-if-exists。

• App\ の PSR-4 マッピングが src/ 以外を指していると 拒否

します（public/index.php が App\AppConfigurator＝src/ 前提のため）。

• 終了コード: 0 成功 / 1 I/O 失敗 / 2 誤用（composer.json

が無い・JSON でない 等）。

relayer upgrade#

polidog/relayer を上げると、新しいフレームワークバージョンが生成雛形にファイルを追加することがあります。upgrade は既存プロジェクトの構造を、インストール済みフレームワークの構造まで前進させます。relayer init の対になるコマンドです。

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

• extra.relayer.structure_version マーカーを読み、その値から

現行バージョンまでの間に追加されたファイルだけを書き出し、最後にマーカーを前進させます。マーカーを動かす唯一のコマンドです。

• 各ステップは skip-if-exists。編集済みファイルはそのまま

保持され、skip として報告されます（非破壊）。

• 対象は構造差分とマーカーのみ。composer の scripts や

autoload には触れません。それらは加算的で安全なので、必要なら relayer init を再実行してください。

• 冪等。すでに現行バージョンに達していれば「何もすることがない」

と報告して終わります。

• マーカーが無いプロジェクトは relayer init で生成されていない

ため、まず init で現行構造を刻印してください。

• 終了コード: 0 成功／既に最新 / 1 I/O・状態エラー / 2

誤用（composer.json が無い・マーカーが無い 等）。

relayer routes#

src/Pages 配下で検出されたルートを一覧します。パス順にソートされ、メソッド・パス・種別（page / api）・ファイルが並びます。

vendor/bin/relayer routes

• route.php（API ルート）は宣言済み HTTP メソッドを表示。ページは

GET,POST。読めない route.php は隠さず ? ＋警告行で示します。

• src/Pages が無ければその旨を表示して終了します。

relayer routes:compile#

ルート表を事前コンパイルします。既定ではルーターはリクエストごとに src/Pages/ を走査しますが、これを実行するとスナップショットを書き出します:

• <projectRoot>/var/cache/routes/routes.php — 検出済みルート表

デプロイ時に実行します（→ デプロイ）。

vendor/bin/relayer routes:compile

• 存在するかどうかだけがゲート。ファイルがあればルート走査を

スキップし、無ければライブ経路に縮退します — dev はコンパイルしないので常に最新のツリーを反映し stale になりません。

• 走査時の曖昧さ（page と route.php の衝突、ルートグループによる

URL 衝突）は、本番初回リクエストではなくこのコマンドで失敗します。

• 出力は常に上記パス（自動生成・手で編集しない。再生成は同コマンド）。

usephp compile（.psx）とは独立した別ステップで、両方ビルド時に実行します。

• 終了コード: 0 成功 / 1 src/Pages が無い・走査不能・書き込み

失敗。

relayer container:compile#

DI コンテナを事前コンパイルします。既定では Relayer::boot() が毎リクエスト Symfony の ContainerBuilder をビルドして compile() まで回します — 通常これが回避可能なリクエストコストの最大要因です。これを実行すると素の PHP クラス <projectRoot>/var/cache/container/CompiledContainer.php （Polidog\Relayer\Generated\CompiledContainer）にダンプし、本番は再ビルドせずそれを require します。デプロイ時に実行します（→ デプロイ）。

vendor/bin/relayer container:compile

• 存在するかどうかだけがゲート。ファイルがあれば本番はそれを

使い、無ければライブビルドに戻ります。dev はコンパイルしないので常に最新のサービス設定を反映し stale になりません。

• 不正なサービス定義（config/services.yaml / App\AppConfigurator

の構成エラー）は、本番初回リクエストではなくこのコマンドで失敗します。relayer routes:compile と同じ「デプロイ時失敗」性質。

• サービス構成を変えたら再生成します（同コマンドを再実行）。出力は

常に上記パス（自動生成・手で編集しない）。usephp compile（.psx）・routes:compile（ルート表）とは独立した別ステップで、3 つすべてビルド時に実行します。

• ランタイム secret の注意。AppConfigurator::configure() は

デプロイ時に 1 回だけ走り、結果がダンプに焼き込まれます。env を直読みして setParameter() に文字列で渡すとビルド時の値（多くの場合空文字）が本番でも返り続けるため、Fly secrets / Cloud Run env のようにランタイムにしか来ない値は %env(VAR)% プレースホルダで渡してください（サービスと DI 参照）。

• 終了コード: 0 成功 / 1 ビルド / ダンプ / 書き込み失敗。

relayer profiler:clear#

dev プロファイラの記録（var/cache/profiler/*.json）を削除します。詳細は プロファイラ 参照。

vendor/bin/relayer profiler:clear

冪等で、*.json のみ削除（ディレクトリや他ファイルは残す）。空でも成功 0、削除失敗時は報告して 1。

usephp compile#

.psx を事前コンパイルしてリクエスト時のコンパイルを無くすビルドステップです。本番デプロイ（デプロイ）で実行します。

vendor/bin/usephp compile [options] [paths...]

• 各パス（ファイル／ディレクトリ）を走査し .psx をキャッシュ

ディレクトリへコンパイル（ソース絶対パスの sha1 名なのでソースツリーは汚れない）。

• manifest.php（PascalCase コンポーネントの FQCN → 生成パス）と、

Defer 設定を集めた deferred-manifest.php を書き出します（Defer コンポーネント はこれで自動登録）。小文字名の page.psx / layout.psx はコンパイルされますが、マニフェストには載らずパスで直接ロードされます。

• ソースハッシュが *.meta と一致すれば再コンパイルを スキップ

（インクリメンタル）。paths 省略時の既定は <cwd>/components なので、このサイトのような構成では src を明示します。

vendor/bin/usephp compile src                 # src 配下を事前コンパイル
vendor/bin/usephp compile --check src         # CI: 未コンパイルなら失敗

このサイトの記事管理 CLI bin/docs（migrate/list/new/edit/show/ rm/export/import）は relayer ではなくこのサイト固有のツールで、 Turso のストアを直接編集します。フレームワークのコマンドではないので別物として扱ってください（→ デプロイ）。