導入

REST-API 開発環境の作成

SOCKET-MANAGER Framework の REST-API 開発環境は、 Composer の create-project コマンドで簡単に作成できます。

導入コマンド

composer create-project socket-manager/rest-api <任意のプロジェクトフォルダ>

必要要件

REST-API サーバー開発環境を利用するためには、以下の環境が必要です。

● PHP 8.1 以上
● Composer（依存パッケージ管理）
● CLI（コマンドライン）で PHP が実行できる環境

Linux / macOS / Windows のいずれでも動作します。

ディレクトリ構成

プロジェクト構成の概要

create-project によって生成される REST-API 開発環境は、以下のようなディレクトリ構成になっています。

ディレクトリ構成

project/
├─ app/                 … イベントハンドラ / ステートマシンなどの主要クラスの実装
├─ commands/            … カスタムコマンド定義
├─ locale/              … 多言語対応のメッセージ定義
├─ logs/                … ログ出力場所
├─ public/              … 静的ファイル（HTML / JS / CSS）
├─ setting/             … 設定ファイル（app.php / cors.php / parameter.php など）
├─ upload/              … アップロードファイル格納場所
├─ vendor/              … Composer パッケージ
└─ worker               … サーバー起動コマンド

app ディレクトリ

REST-API のイベント処理（イベントハンドラ型 / ステートマシン型）や主要クラスを配置する場所です。
CRUD API や Chunked / SSE / Range などの実装をここにまとめます。

commands ディレクトリ

REST-APIサーバー構築に必要となるカスタムスキャフォールディングコマンド群の定義が格納されています。
カスタムコマンドの作成方法については以下のページを参照してください。

locale ディレクトリ

多言語対応のメッセージ定義を配置するディレクトリです。
error.php にはレスポンスで送信時のステータスコードに対応する一般的な理由句のメッセージが定義されています。

logs ディレクトリ

現在はサンプルサーバーから出力されるログ出力先として利用しています。

public ディレクトリ

サンプル画面や静的ファイルを配置するディレクトリです。
サンプル環境では sample.html がここに含まれています。

setting ディレクトリ

REST-API サーバーの動作を制御する設定ファイル群です。
詳細は「設定ファイル（Setting）」カテゴリで解説します。

upload ディレクトリ

現在はサンプルサーバーで取得する Multipart データやチャンク転送で受信するアップロードファイルの格納先として利用しています。

worker（サーバー起動コマンド）

REST-API サーバーを起動するための CLI コマンドです。
イベントハンドラ型 / ステートマシン型のサンプルが用意されています。

設定ファイルの概要

REST-API サーバーの動作制御

setting ディレクトリには、REST-API サーバーの動作を制御する重要な設定ファイルが含まれています。

● app.php … アプリ全体の基本設定（タイムゾーン / ロケール）
● cors.php … CORS ヘッダの制御
● parameter.php … ホスト / ポート / サイズ制限 / KeepAlive など
● parser.php … HTTP ボディパーサーの設定
● routing.php … ルーティング設定（Expect / 404 / サイズ制限チェック）

これらの詳細は「設定ファイル（Setting）」カテゴリで個別に解説します。

設定ファイルの読み込みルール（重要）

REST-API サーバーでは、メイン処理クラス内の $setting_files プロパティによって、使用する設定ファイル名が決定されます。

setting_files プロパティ（抜粋）

protected array $setting_files = [
    'cors'      => 'cors',
    'parameter' => 'parameter',
    'parser'    => 'parser',
    'routing'   => 'routing'
];

特に parameter / parser / routing の 3 つは null を指定することが許可されています。
null が指定された場合は、上記のデフォルト名（parameter.php / parser.php / routing.php）が自動的に読み込まれます。

そのため、これら 3 つの設定ファイルは、基本的な設定項目を含んだ状態で必ず setting ディレクトリに配置しておく必要があります。
（削除したり、空ファイルにするとサーバー動作に影響が出る可能性があります。）

サーバー起動

イベントハンドラ型の起動

サーバー起動

php worker app:event-handler-sample

ステートマシン型の起動

サーバー起動

php worker app:state-machine-sample

サンプル画面の表示

サンプル画面のURL

http://localhost:10000/sample.html

サンプルサーバーは Web サーバーを兼ねているため、別途 Web サーバーは不要です。
ドキュメントルートは setting/parameter-sample.php で変更できます。

開発フローの全体像

1. ルーティングを定義する

routing.php ファイルに URL とイベント処理の対応を設定します。

2. イベント処理を実装する

app ディレクトリにイベントハンドラ型 / ステートマシン型のイベント処理を実装します。

3. レスポンスを返す

ResponseWrapper を使って JSON / text / file / chunked / SSE / Range などを返します。

4. 必要に応じて設定を調整する

CORS、パラメータ、パーサー、ルーティング設定などを調整し、サーバーの動作を最適化します。