【REST-APIサーバー開発環境】

はじめに

SOCKET-MANAGER Framework の REST-API サーバー開発環境は、リアルタイム通信基盤の上に構築された高速・堅牢な PHP 製 API フレームワークです。
ステートマシン内蔵のイベントループにより、Chunked Transfer・SSE・Range 送信などの段階的なレスポンス処理を安定して実行できます。

REST-API は CUEI アーキテクチャ上で動作し、通信方式に依存しない統一モデルを採用しています。
これにより、WebSocket/TCP/UDP と REST-API を同一プロセス内で安全に共存させることが可能です。
また、PSR-7 準拠の Request/Response を採用しているため、OAuth2 を含む外部ライブラリとの統合や既存 PHP アプリケーションとの連携も自然に行えます。

実装方式は「イベントハンドラ型（即時処理）」と「ステートマシン型（段階処理）」の 2 方式から選択でき、軽量な CRUD API から状態遷移を伴う高度な API まで柔軟に対応します。
Laravel とのネイティブ連携にも対応しており、Logger・Eloquent・Service Container などのリソースを追加実装なしで利用できます。

REST-API の内部構造や実装方式、設定ファイル、サンプルコードについては、以下の各カテゴリで詳しく解説しています。


REST-API の基盤となる内部構造（CUEI / Event / IPC）については、 以下のページもあわせて参照してください。

Laravel とのネイティブ連携方法については、 ▶Laravelと連携する（既成プロジェクトを連携） で詳しく解説しています。
（REST-API 環境を連携する場合は MainForRestApi のメイン処理クラスも別途変換する必要があります。上記リンク先で紹介されているビルトインコマンドを使って変換できます。）

メニュー構成


BASIC-CONCEPTS（基礎・コンセプト）

REST-API サーバー開発環境の全体像を理解するための基礎知識をまとめたカテゴリです。
フレームワークの思想、構造、導入手順をここから学べます。

▶コンセプトと構造
フレームワークの思想、CUEI の全体像、REST-API に強い理由をまとめています。

▶導入と構成
インストール方法、ディレクトリ構成、設定ファイル、起動方法を説明します。


QUICK-START（クイックスタート）

「サンプルを利用する場合」や「新規でサーバーを作る場合」など、ケース別での最短で動かす方法をここから学べます。

▶サンプルを利用する場合
最短で API を作るための手順とサンプルをまとめています。

▶新規でサーバーを作る場合
最短でサーバーを１から作るための手順とサンプルをまとめています。


CUEI-FOUNDATION（CUEI / 基盤技術）

REST-API を支える内部アーキテクチャ（CUEI）と、PSR-7 やルーティングなどの基盤技術を扱うカテゴリです。
REST-API がどのように動作しているか、内部構造を理解したい場合に役立ちます。

▶CUEIとの実装レベルでの関係
Communication / Union / Event / IPC の4要素を深掘りします。

▶PSR-7 ラッパーの仕様
Request / Response Wrapper の完全版とコンテキスト変数を使った使用方法を説明します。

▶ルーティングの概要
ルーティングの基本思想と仕組みを概念的に解説するページです。


IMPLEMENT-STYLES（実装方式）

REST-API を実装するための 2 つの方式（イベントハンドラ型 / ステートマシン型）を体系的に解説するカテゴリです。
API の性質に応じて、どちらの方式を選ぶべきか判断できるようになります。

▶イベントハンドラ型実装
単一メソッドで即時処理を行う軽量な REST-API 実装方式を解説するページです。

▶ステートマシン型実装
UNIT を段階的に遷移させて処理するステートマシン方式の実装方法を解説するページです。


OTHER-CLASSES（その他主要クラスの実装）

REST-API サーバーを構成する主要クラス（メイン処理 / コンテキスト / パーサー / Parallel）の実装方法とスキャフォールディングの種類をまとめたカテゴリです。
REST-API の内部処理をカスタマイズしたい場合に参照します。

▶メイン処理クラス実装
REST-API サーバー全体の動作を統括する中心クラスの構造と役割を解説するページです。

▶コンテキストクラス実装
リクエスト処理中の状態・依存情報を管理するコンテキストの仕組みを解説するページです。

▶パーサークラス実装
HTTP ボディの解析や入力検証を行うパーサーの拡張方法を解説するページです。

▶Parallelクラス実装
REST-API と並行して動作する常駐処理やモジュール連携を実現する Parallel クラスの実装方法を解説するページです。

▶スキャフォールディング
REST-API 開発に必要な各種クラスを自動生成するスキャフォールディング機能の種類をまとめたページです。


SETTING-FILES（設定ファイル）

REST-API サーバーの動作を制御する各種設定ファイル（ルーティング / パラメータ / CORS / パーサー）を解説するカテゴリです。
サーバーの挙動を調整したい場合に必要な情報がまとまっています。

▶ルーティング設定
ルーティング設定ファイルの書式と仕様を詳しく解説するリファレンスです。

▶基本パラメータ設定
ホスト、ポート、サイズ制限、KeepAlive など、サーバー動作の中心設定です。

▶CORS 設定
allow-origins や allow-headers など、CORS ヘッダの制御を行います。

▶パーサー設定
JSON / XML などの HTTP ボディパーサーや Content-Type 別のパーサーの設定を行います。


ADVANCED（より高度な使い方）

REST-API サーバー開発環境をさらに拡張するための高度な機能をまとめたカテゴリです。
カスタムコマンド、Laravel 連携、システム設定など、応用的なトピックを扱います。

▶カスタムコマンド作成機能
独自の CLI コマンドを追加し、開発フローを拡張するための仕組みを解説するページです。

▶Laravelと連携する
Laravel と統合し、既存アプリケーションと連携させる方法を解説するページです。

▶システム設定ファイル
フレームワーク全体の動作を制御するシステム設定ファイルの構造と役割を解説するページです。


基盤技術について（REST-API から見た概要）

REST-API サーバー開発環境は、SOCKET-MANAGER Framework 本体が提供するSocketManager / RuntimeManager / SimpleSocketといった基盤モジュールの上に構築されています。

これらのモジュールは、フレームワークに内蔵されたUNIT（処理単位）とキュー（状態遷移）によるステートマシンを用いて動作し、複数のモジュールが同一プロセス内で共存できる柔軟なアーキテクチャを持っています。

REST-API 環境では、この基盤技術のうちSocketManager の特定構成をプリセット化したものを利用しており、開発者は REST-API に必要な部分だけを扱えばよいように設計されています。

また、ステートマシンを基盤に持つことで、一般的なイベント駆動型ソリューションでは難しいChunked Transfer / SSE / Range送信 / IPC（サーバー間通信）といった高度な処理を安定して実現できます。

基盤技術の詳細なアーキテクチャ（UNIT / キュー構造、モジュール構成、マルチサーバー動作など）については、フレームワーク本体ドキュメント（ADVANSEDメニューカテゴリ）の▶アーキテクチャ のページを参照してください。

特徴


REST-API / RESTful-API 対応

  • 標準的な REST-API 設計に加え、RESTful-API のリソース指向設計にも対応
  • PSR-7準拠の Request / Response を採用
  • OAuth2 など PSR-7 対応モジュールとの連携が容易
PSR-7 公式仕様：
https://www.php-fig.org/psr/psr-7/


クロスプラットフォーム（PHP環境）

  • PHP が動作する環境であれば OS を問わず利用可能
  • Linux / Windows で動作確認済み

ステートマシン内蔵

  • Chunked Transfer（チャンク転送）
  • Server-Sent Events（SSE）
  • Range送信
  • IPC（サーバー間通信）
  • 長時間接続・状態遷移を伴う API に最適

イベントハンドラ型 / ステートマシン型の2方式

  • イベントハンドラ型：単一のイベントハンドラで完結する一般的な REST API に最適
  • ステートマシン型：状態遷移を伴う API（Chunked / SSE / Range）に最適

実装形態


イベントハンドラタイプ

単一のイベントハンドラで処理を行うシンプルな方式。
一般的な CRUD API や短時間で完結する処理に適しています。
  • シンプルで学習コストが低い
  • 小規模〜中規模 API に最適

ステートマシンタイプ

UNIT（状態）単位で処理を分割し、状態遷移を伴う API を実装する方式。
以下のようなケースで特に強みを発揮します。
  • Chunked Transfer（確実な分割送信）
  • SSE（再接続後の継続受信）
  • Range送信（部分的なデータ送信）
  • IPC を伴う複雑な状態管理
  • 長時間接続が必要な API

サンプル構成

REST-API サーバー開発環境には、動作確認用のサンプルが同梱されています。
イベントハンドラ型 / ステートマシン型の両方を用意しています。

● ユーザー情報操作（CRUD）

  • GET：ユーザー一覧取得
  • POST：新規ユーザー作成
  • PUT：ユーザー全体更新
  • PATCH：ユーザー部分更新
  • DELETE：ユーザー削除

● Multipart アップロード

  • アップロード済みファイルの確認
  • Multipart形式でのファイルアップロード

● Chunked アップロード

  • Chunkedアップロード済みファイルの確認
  • curl コマンドによるアップロード（ブラウザ制約回避のため）

● チャンク転送デモ

ステートマシンタイプでは、Chunked Transfer による分割送信が確実に行われます。
以下の GIF アニメでは、5秒間隔でチャンクが送信される様子を確認できます。

Chunked Transfer による5秒間隔の分割送信デモ

● SSE（再接続対応）デモ

Server-Sent Events（SSE）では、クライアントが切断された場合でも再接続後に続きから受信できます。
以下の GIF アニメでは、接続断 → 再接続 → 続きのイベント受信までの流れを確認できます。

SSE の再接続後に続きを受信するデモ

● Rangeヘッダを使った分割送信デモ


● IPC / マルチサーバーサンプル

サーバー間通信を利用したランチャーのカスタムモニタリング（同時接続ユーザー数など）連携の実装例。

導入方法

以下のコマンドで REST-API 開発環境を作成します。
composer create-project socket-manager/rest-api <任意のプロジェクトフォルダ>

サンプルの起動方法


● イベントハンドラタイプのサーバー起動

php worker app:event-handler-sample

● ステートマシンタイプのサーバー起動

php worker app:state-machine-sample

● ブラウザでサンプル画面を表示

http://localhost:10000/sample.html
※ サンプルサーバーが Web サーバーを兼ねているため、別途 Web サーバーは不要
※ ドキュメントルートは ./setting/parameter-sample.php で変更可能（デフォルト：public/）

関連リンク