CLI コマンド#

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

vendor/bin/rosanna も入りますが、その compile は Relayer が使う deferred manifest を書き出さないので使いません。

relayer#

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

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

サブコマンドのあとの -h / --help は使い方を表示して 0、未知のオプション（- で始まる引数）は使い方を出して 2 で終わります。どちらもファイルを書く前に止まります。

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。
• .env.local（APP_ENV=dev）を書くのは 新規プロジェクトだけです。.env もマーカーもなく、src/Pages・src/AppConfigurator.php・public/index.php・ public/worker.php のどれもないものを新規とみなします。書く前に .gitignore が .env.local を除外していることを確かめ（無ければ /.env.local を足します）、確かめられなければ失敗します。.env.local が Git で追跡されているときは作りません。既存のプロジェクトや clone した直後は echo APP_ENV=dev >> .env.local を実行します（→ 環境変数）。
• 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（=）として報告されます（非破壊）。
• 以前に配布したファイルの内容が変わる場合もあります（例: Dockerfile に本番ターゲットが加わる）。この置換は「そのファイルが未編集であること」がゲートです。いずれかのフレームワークバージョンが書いたバイト列と完全一致する場合だけ置き換え（~）、少しでも編集していれば一切触れず keep（!）として報告します。新しいテンプレートを取り込みたい場合は、自分の変更を退避してファイルを削除し、 relayer init を実行します。
• 未編集の .env を置き換えるときは、そこにある APP_ENV=dev を gitignore 対象の .env.local に移します。ファイルがなければ作り、APP_ENV を指定していなければ行を追記し、指定済みなら触りません。編集済みの .env は残し、.env.local も書かないので、APP_ENV は自分で確かめてください。書く前に .gitignore が .env.local を除外していることを確かめ、確かめられなければ何も書きません。 .env.local が Git で追跡されていると .env と .env.local をそのままにして失敗するので、git rm --cached .env.local を実行してコミットし、再実行します。
• 対象は構造差分とマーカーのみ。composer の scripts や autoload は、存在しないクラスを指すアセット publish スクリプトを Polidog\Rosanna\Defer\Installer\AssetInstaller::publish に置き換える以外は触れません。足りないものは加算的で安全なので、必要なら relayer init を再実行してください。
• 冪等。すでに現行バージョンに達していれば「何もすることがない」と報告して終わります。
• マーカーが無いプロジェクトは relayer init で生成されていないため、まず init で現行構造を刻印してください。
• 終了コード: 0 成功／既に最新 / 1 I/O・状態エラー / 2 誤用（composer.json が無い・マーカーが無い 等）。

relayer routes#

src/Pages 配下で検出されたルートを一覧します。パス順にソートされ、メソッド・パス・種別（page / api / native）・ファイルが並び、ルートミドルウェアがあれば末尾に (php) / (native) 付きで示します。

vendor/bin/relayer routes

• route.php（API ルート）は宣言済み HTTP メソッドを表示。ページは GET,POST。読めない route.php は隠さず ? ＋警告行で示します。
• src/Pages が無ければその旨を表示して終了します。

relayer compile#

デプロイ用のアーティファクトをまとめて生成します。.psx（src/Pages と src/Components。無いディレクトリは飛ばします）、routes:compile、container:compile を順に実行し、最初の失敗で止まります。

vendor/bin/relayer compile

relayer native:build#

src/Pages 配下の route.go と middleware.go を var/cache/native/bin にコンパイルします。Go が必要なので relayer compile には含まれません（→ ネイティブルート）。

relayer routes:compile#

ルート表と dispatch pipeline を事前コンパイルします。既定ではルーターはリクエストごとに src/Pages/ を走査し、dispatch listener chain もコンテナタグから組み立てます。これを実行すると 2 つのスナップショットを書き出します:

• <projectRoot>/var/cache/routes/routes.php — 検出済みルート表。
• <projectRoot>/var/cache/routes/dispatcher.php — final class CompiledDispatcher implements DispatchListener。登録済み listener をコンストラクタで受け取り、各 hook を同じ順序で転送します。ファイルを開けば、どの listener がどの順で呼ばれるかが静的に見えます。

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

vendor/bin/relayer routes:compile

• 存在するかどうかだけがゲート（2 ファイルは独立）。routes.php があればルート走査をスキップし、dispatcher.php があれば dump を読みます。無ければそれぞれライブ経路に戻ります。dev はコンパイルしないので常に最新のツリーと listener セットを反映し stale になりません。 dispatcher.php が無い場合も同じ relayer.dispatch_listener タグが RuntimeDispatcher 経由で同じ順に呼ばれるため、観測される挙動は同じです。
• 走査時の曖昧さ（page と route.php の衝突、ルートグループによる URL 衝突）は、本番初回リクエストではなくこのコマンドで失敗します。
• dispatcher.php が焼き込むのは listener のサービス ID（クラス名）だけです。コンストラクタ引数は焼き込まれず、env 由来の値を持つ listener もリクエスト時の live container から解決されます（サービスと DI の container:compile 注意点とは独立）。
• 出力は常に上記 2 パス（自動生成・手で編集しない。再生成は同コマンド）。 rosanna-defer 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 と同じ「デプロイ時失敗」性質。
• サービス構成を変えたら再生成します（同コマンドを再実行）。出力は常に上記パス（自動生成・手で編集しない）。rosanna-defer compile（.psx）・routes:compile（ルート表）とは独立した別ステップで、3 つすべてビルド時に実行します。
• 終了コード: 0 成功 / 1 ビルド / ダンプ / 書き込み失敗。

relayer profiler:clear#

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

vendor/bin/relayer profiler:clear

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

rosanna-defer compile#

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

vendor/bin/rosanna-defer compile [options] [paths...]

• 各パス（ファイル／ディレクトリ）を走査し .psx をキャッシュディレクトリへコンパイル（ソース絶対パスの sha1 名なのでソースツリーは汚れない）。
• manifest.php（PascalCase コンポーネントの FQCN → 生成パス）と、 Defer 設定を集めた deferred-manifest.php を書き出します（Defer コンポーネント はこれで自動登録）。小文字名の page.psx / layout.psx はコンパイルされますが、マニフェストには載らずパスで直接ロードされます。
• 存在しないパスを渡すと exit 1 です（新規プロジェクトには src/Components がないので、まとめてビルドするなら relayer compile を使います）。
• manifest は実行のたびに書き直されます。src/Components と src/Pages は 1 回のコマンドにまとめて渡します。
• ソースハッシュが *.meta と一致すれば再コンパイルを スキップ （インクリメンタル）。paths 省略時の既定は <cwd>/components なので、このサイトのような構成では src を明示します。

未知のオプションは exit 1 です。--check と --watch は同時に使えません。

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

vendor/bin/rosanna-defer publish は public/rosanna-defer.js を配置します。 relayer init が composer の post-install-cmd / post-update-cmd に Polidog\Rosanna\Defer\Installer\AssetInstaller::publish を登録するので、通常は composer install が自動で行います。

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