Naify\Router\RequestContext クラス

リクエストコンテキスト — Router の世界の中心

PSR の ServerRequest/Response をラップし、Router 以下の全コンポーネントに 統一的なアクセス手段を提供する。PSR との接点はこのクラスに集約される。 さらに、この request がどの Application から発行されたかを保持し、 controller や middleware から app/config へ届く導線も提供する。

普段は getMethod(), getPath(), getParam() 等の便利メソッドを使い、 PSR インターフェースが必要な場合のみ getPsrRequest() / getPsrResponse() を使う。

使用例

// グローバル変数から生成（Application が呼ぶ）
$ctx = RequestContext::fromGlobals($app);

// PSR オブジェクトから生成
$ctx = RequestContext::build($request, $response, $app);

// 普段使い
$ctx->getMethod();           // 'GET'
$ctx->getPath();             // '/hello/world'
$ctx->getParam('key');       // POST + GET パラメータ
$ctx->getUrlParam('id');     // URL パラメータ

// ルーティング情報
$ctx->getRoutingHandler();   // 'NaifyApp\Controllers\IndexController'
$ctx->getRoutingAction();    // 'indexAction'
$ctx->getRouteName();        // 'home'（設定時のみ）
$ctx->getConfig();           // 現在のアプリ設定

// PSR が必要な時だけ
$ctx->getPsrRequest();          // ServerRequestInterface
$ctx->getPsrResponse();         // ResponseInterface

プロパティ

名前型説明
private $app App この request を発行したアプリケーション
private $request ServerRequestInterface PSR-7 リクエスト 8.4 → asymmetric visibility
public $response ResponseContext レスポンスコンテキスト（ミュータブル操作面） 8.4 → asymmetric visibility
private $urlParam array URL パラメータ（ルーティング引数）
private $params array リクエストパラメータ（POST + GET を統合した簡易ビュー）
private $paramOverrides array setParam() で明示的に指定した値
private $uploadedFiles ?UploadedFiles 現在の request のアップロード一覧。初回取得時に構築する
private $routingHandler ?string ルーティング先のハンドラクラス名
private $routingAction ?string ルーティング先のアクション名
private $routeName ?string ルート名（任意）
private $routingError ?RouteException ルーティングエラー

メソッド

メソッド説明
public static fromGlobals(App $app): static $_SERVER 等のグローバル変数から生成する
public static build(ServerRequestInterface $request, ResponseInterface $response, App $app): static PSR オブジェクトから生成する（PSR との唯一の接点）
query params と parsed body は、この時点で `params` に統合される。
同名キーがある場合は後勝ちになるため、parsed body 側の値が優先される。
public getApp(): App この request を発行したアプリケーションを取得する
public getConfig(): AppConfig 現在のアプリ設定を取得する
public getMethod(): string HTTP メソッドを取得する
public getPath(): string リクエストパスを取得する
public getRequestUrl(?string $key): ?string REQUEST_URI の情報を取得する
引数なし: REQUEST_URI をそのまま返す
引数あり: parse_url + pathinfo の結果から指定キーを返す

指定可能なキー:
- scheme, host, port, path, query, fragment (parse_url)
- extension, filename, dirname, basename (pathinfo)

Usage:
$ctx->getRequestUrl(); // '/test/compatibility.json?v=1'
$ctx->getRequestUrl('path'); // '/test/compatibility.json'
$ctx->getRequestUrl('extension'); // 'json'
$ctx->getRequestUrl('query'); // 'v=1'
$ctx->getRequestUrl('filename'); // 'compatibility'
public getPsrRequest(): ServerRequestInterface PSR-7 リクエストオブジェクトを取得する 8.4 → property hooks
public setPsrRequest(ServerRequestInterface $request): static PSR リクエストを設定する（ミドルウェアが加工した Request を Context に同期する）
params も再構築される（POST + GET 統合ビュー）。setParam() の明示値は維持する。
アップロード情報が同じなら取得済みの UploadedFile と移動状態も維持する。
情報が変わった場合は一覧を破棄し、次の取得時に新しい情報から構築する。
public getPsrResponse(): ResponseInterface レスポンスを取得する
通常のリクエスト処理中は、コントローラーやミドルウェアが最後に
setPsrResponse() した時点の Response が返る。

注意: 例外発生時のレスポンスは信頼できない。
リクエスト処理中やミドルウェアの復路で例外が発生した場合、
この Response は例外発生前の最後の正常な状態のスナップショットであり、
処理が途中で止まっている可能性がある。
これは PSR-15 準拠のフレームワークでも同じ制約で、
PSR では例外発生時に Response 自体が取得できない。
Naify では Context 経由で最後の Response がログとして参照できる利点がある為、
あえて消さずに残している。
エラーハンドラはこの Response を出力に使わず、新しい Response を作ること。 8.4 → property hooks
public setPsrResponse(ResponseInterface $response): static PSR レスポンスを設定する（ミドルウェアが加工した Response を反映する）
public getUrlParam(string $name, mixed $default): mixed URL パラメータを取得する
public setUrlParam(string $name, mixed $value): static URL パラメータを設定する
public setUrlParams(array $urlParams): static URL パラメータを一括設定する
Route の match() 結果をまとめて Context と PSR request attribute へ反映する。
public getUrlParamAll(): array 全 URL パラメータを取得する 8.4 → property hooks
public getParam(string $name, mixed $default): mixed リクエストパラメータを取得する（POST + GET）
public setParam(string $name, mixed $value): static リクエストパラメータを設定する
public getParamAll(): array 全リクエストパラメータを取得する（POST + GET） 8.4 → property hooks
public getUploadedFile(array|string $name): ?UploadedFile フォームの入力名を指定して、アップロードファイルを 1 件取得する。
入力名が存在しなければ null。未選択や受信失敗はエラー情報を持つ UploadedFile を返す。
保存前に isValid() を確認し、失敗理由が必要なら getError() を読む。
photos[] の 1 件は ['photos', 0] のようにキー配列で指定する。ドット・角括弧は分解しない。

Usage:
$file = $ctx->getUploadedFile('avatar');
if ($file !== null && $file->isValid()) {
$file->moveTo($destination);
}
public getUploadedFiles(array|string|null $name): array アップロードのツリーを取得する。配列入力の名前を指定するとその配下を返す。
入力名・数値キー・入れ子を保ち、末端が UploadedFile になる。未選択や受信失敗も含む。
例: getUploadedFiles() で全件、getUploadedFiles('photos') で photos[] の一覧、
getUploadedFiles(['form', 'photos']) で form[photos][] の一覧を取得する。
単一ファイルを指定した場合は配列に包まず例外にするので、getUploadedFile() を使う。
private getUploadCollection(): UploadedFiles アップロードの初回取得時に一覧を構築し、同じリクエスト内で共有する。
全件の正規化と入力名の探索は UploadedFiles に任せる。
オブジェクトを共有することで、別の取得口からも移動済み状態を確認できる。
public getCookie(string $name, mixed $default): mixed クッキー値を取得する
public getServer(string $name, mixed $default): mixed $_SERVER値を取得する
public getRoutingHandler(): ?string ルーティング先のハンドラクラス名を取得する 8.4 → property hooks
public getRoutingAction(): ?string ルーティング先のアクション名を取得する 8.4 → property hooks
public getRouteName(): ?string ルート名を取得する 8.4 → property hooks
public setRouteName(string $name): static ルート名を設定する
public setRoutingInfo(string $handler, ?string $action, ?string $name): static ルーティング情報を設定する（Router が呼ぶ）
public getRoutingError(): ?RouteException ルーティングエラーを取得する 8.4 → property hooks
public setRoutingError(RouteException $error): static ルーティングエラーを設定する（Router のエラーハンドラが呼ぶ）