ルーティング設定 | REST-APIサーバー開発環境

このページでは、REST-API サーバーで使用する ルーティング設定ファイル の詳細仕様について解説します。

ルーティング設定ファイルは、REST-API の動作を決定する重要な設定であり、 HTTP メソッド + URI → イベントハンドラのメソッド（またはステートマシンのメソッド） の対応関係を定義します。

なお、設定ファイル名は固定ではなく、メイン処理クラスの $setting_files['routing'] プロパティにより任意の名称を指定できます。

メイン処理クラスでの設定方法は ▶メイン処理クラス実装（設定ファイル指定）を参照してください。

ルーティング設定ファイルは、return によって連想配列を返す形式で記述します。

主なキーは次の 3 つです。

routes：ルーティング定義のリスト
expect：Expect ヘッダ受信時のルーティング先
mismatch：ルーティングミスマッチ時のルーティング先

<?php
return [
    'routes' => [
        // ルーティング定義
    ],
    'expect'   => 'expectHeader',
    'mismatch' => null,
];

routes は REST-API サーバーが扱うすべてのルートを定義する配列です。

ルートは次の 2 種類の形式で記述できます。

単独ルート
グループ化されたルート

1. 単独ルート

単独ルートは次の 3 つのキーで構成されます。

method：HTTP メソッド
uri：対象 URI
event：呼び出すイベント処理メソッド名

[
    'method' => 'get',
    'uri'    => '/api/v1/sse/stream',
    'event'  => 'getStreamBySse',
],

2. グループ化されたルート

共通の URI プレフィックスを持つ複数ルートをまとめる形式です。

[
    'uri'   => '/api/v1/users',
    'group' => [
        [
            'method' => 'get',
            'uri'    => '/:id([0-9]+)?',
            'event'  => 'getUsers',
        ],
        [
            'method' => 'post',
            'uri'    => '/',
            'event'  => 'postUser',
        ],
    ],
],

注意：
グループの uri には正規表現を使用できません。
正規表現を使用する場合は子要素側の uri に記述してください。

URI にはパラメータや正規表現を含めることができます。

1. 通常のパラメータ

/:id … 必須パラメータ
/:id? … 省略可能パラメータ

2. 正規表現パラメータ

/:id([0-9]+) のように括弧で正規表現を指定できます。

3. URI 全体を正規表現で扱う

:/...: のようにコロンで囲む形式です。

この形式では 名前付きキャプチャ が使用できます。

:/(?P<id>[0-9]+)/files/(?P<type>[a-z]+)$:

上記の例では id と type の 2 つのパラメータを同時に取得できます。

正規表現の詳細は PHP 正規表現マニュアルを参照してください。

4. ワイルドカードパラメータ（アスタリスク）

URI の一部に * を指定すると、その位置の文字列がパラメータ名となり、 それ以降の URI 全体がパラメータ値として扱われます。

/api/v1/*/detail

上記の例では、* に該当する部分がパラメータ名となり、その後ろの URI 部分がそのパラメータの値として取得されます。

この仕組みは、階層が深い URI や任意のパス構造を柔軟に扱いたい場合に有効です。

パラメータはコンテキストクラスから取得できます。

$id = $ctx->request()->params('id');

各ルートの event キーには、呼び出すイベントハンドラのメソッド名（またはステートマシンのメソッド名）を指定します。

イベント処理（クラス）の実体はメイン処理クラスの設定によって決定されます。

メイン処理クラスでの設定の詳細は ▶メイン処理クラス実装（クラス名指定）を参照してください。

expect にメソッド名を指定した場合

Expect: 100-continue を受信した際、そのメソッドが呼び出されます。

expect が null の場合のデフォルト動作

Expect ヘッダの値が 100-continue ではない → 417 Expectation Failed
HTTP メソッドがルーティング設定に存在しない → 405 Method Not Allowed
HTTP ヘッダ + HTTP ボディの合計サイズが制限超過 → 413 Payload Too Large
※ 基本パラメータの limit_request_size を参照（▶基本パラメータ設定（各パラメータの説明））
HTTP ボディサイズが制限超過 → 413 Payload Too Large
※ 基本パラメータの limit_body_size を参照（▶基本パラメータ設定（各パラメータの説明））

mismatch にメソッド名を指定した場合

指定したメソッドが呼び出されます。

mismatch が null の場合のデフォルト動作

404 Not Found を返します。

ルーティング設定ファイルは CLI コマンドで自動生成できます。

php worker custom:setting-routing <ファイル名>

<ファイル名> は任意の名前を指定できます。
生成したファイル名はメイン処理クラス側で設定可能です。
同名ファイルが存在する場合は警告して終了します。

<プロジェクトルート>/setting/

このページでは、REST-API サーバーにおけるルーティング設定ファイルの 完全仕様 を解説しました。

ルーティングの思想や概要については ▶ルーティングの概要を参照してください。

本ページの内容を理解することで、REST-API のルーティングをより柔軟かつ堅牢に設計できるようになります。

【ルーティング設定】

はじめに

設定ファイルの構造

routes セクションの構造

1. 単独ルート

2. グループ化されたルート

URI パラメータ仕様

1. 通常のパラメータ

2. 正規表現パラメータ

3. URI 全体を正規表現で扱う

4. ワイルドカードパラメータ（アスタリスク）

パラメータの取得方法

イベント処理の指定

Expect ヘッダ処理（詳細仕様）

expect にメソッド名を指定した場合

expect が null の場合のデフォルト動作

未定義ルート（ミスマッチ）処理

mismatch にメソッド名を指定した場合

mismatch が null の場合のデフォルト動作

スキャフォールディング（CLI）

おわりに