GitHub

OxPHP ドキュメント

OxPHP は、nginx + PHP-FPM を単一のプロセスで置き換える高性能な PHP アプリケーションサーバーです。TLS、圧縮、レート制限、ヘルスチェック、Prometheus メトリクス、SSE ストリーミング、永続的なワーカーモードを標準搭載しています。

なぜ OxPHP なのか

本番環境の一般的な PHP アプリケーションは、複数のコンテナで構成されます。nginx、PHP-FPM、場合によっては別途 TLS プロキシやメトリクスエクスポーターも必要です。設定はこれらに分散しており、すべてを連携させるにはソケット設定やタイムアウト、パスを同期させ続けなければなりません。OxPHP は、このスタック全体を単一のコンテナで置き換えます。その内部にあるのは、HTTP 接続を受け付け、PHP を実行し、静的ファイルを配信する 1 つのプロセスだけです。

サーバーは、適切なデフォルト設定によりそのまま動作します。細かな調整は環境変数で行います。TLS は 2 つの変数（TLS_CERT、TLS_KEY）で有効化でき、レート制限は 1 つ（RATE_LIMIT）で、圧縮はデフォルトで有効です。nginx の設定を編集したり、別途モジュールをビルドしたりする必要はありません。

専用の内部ポートでは、ヘルスチェック（/health に加え、Kubernetes のプローブ種別ごとの専用エンドポイント）、Prometheus メトリクス（/metrics）、設定のスナップショット（/config）が利用できます。これだけで、追加のサイドカーコンテナなしに Kubernetes の liveness/readiness プローブや Grafana との接続に十分対応できます。

ログは構造化 JSON です。各行にメソッド、パス、ステータス、レスポンスタイム、リクエストIDが含まれます。Loki や Elasticsearch をはじめ、あらゆるツールで追加の grok パターンなしに簡単にパースできます。

リクエストごとに PHP の状態が再構築されないワーカーモードを試すには、WORKER_MODE_ENABLED=true と ENTRY_FILE=worker.php を設定します。フレームワークは一度だけ初期化され、その後は再読み込みなしで数千件のリクエストを処理します。従来のモードに戻すには、この変数を削除してください。

OxPHP には、通常は別途ツールやサードパーティライブラリを必要とする以下の機能も含まれています。

  • 静的ファイル配信 — インメモリキャッシュ、ETag/Last-Modified、自動 MIME タイプ判定
  • 3 つのルーティングモード — ファイルベース、フレームワーク、SPA（ENTRY_FILE によって選択。永続的なワーカーモードはこれらを独自のルーティングに置き換え、静的ファイルとして提供されないすべてのリクエストを .php のエントリースクリプトに引き渡す）
  • 早期レスポンス — レスポンスを即座に送信し、バックグラウンド処理を継続
  • ワーカーモード — ファイバー多重化を備えた永続的な PHP ワーカー
  • SSE ストリーミング — PHP からのリアルタイム Server-Sent Events
  • 非同期 Promise — ワーカーをブロックせずに PHP クロージャをバックグラウンドで実行
  • 共有状態 — プロセス全体で使える並行プリミティブ（Counter、Flag、Once、Mutex、Channel、Map、Pool）により、ワーカーは Redis や APCu なしで協調可能
  • デコレーター — PHP 8 の属性を介した呼び出しのインターセプト
  • 分散トレーシングと APM — W3C Trace Context、OpenTelemetry、データベース/HTTP/キャッシュ/ファイル呼び出しの自動計装、PHP トレーシング SDK

はじめに

  • クイックスタート — 5 分以内に最初の OxPHP アプリケーションをビルドして実行
  • インストール — システム要件とインストール方法
  • Docker ガイド — Dockerfile、Compose 設定、ボリューム、デプロイパターン
  • コマンドラインインターフェース — oxphp コマンドの文法: serve、単一の PHP スクリプトを実行する run、config、--user による権限降格
  • 移行 — nginx + PHP-FPM、FrankenPHP、RoadRunner からの移行: ルーティングモード、設定の対応関係、挙動の違い、引き継がれないもの

運用

機能

  • ルーティング — 3 つのルーティングモード: 従来のファイルマッピング、フレームワークのフロントコントローラー、SPA フォールバック。ワーカーモードはこれらに代わる独自のルーティングモードであり、.php の ENTRY_FILE を必要とし、静的ファイルとして提供されないすべてのリクエストを受け取る
  • 静的ファイル — ファイルキャッシュ、MIME 判定、ETag/Last-Modified ヘッダー、ストリーミング
  • ワーカーモード — リクエスト間で自動的にソフトリセットされる永続的な PHP ワーカー
  • ファイバー多重化 — 協調的マルチタスクにより、ワーカースレッドごとに数百件の並行リクエストを処理
  • 圧縮 — テキストベースのレスポンス向けの Brotli、Zstandard、gzip（クライアントごとにネゴシエーション）
  • TLS — 証明書と鍵の設定による組み込みの TLS 終端
  • レート制限 — ウィンドウと上限を設定できる IP 単位のレート制限
  • タイムアウト — ヘッダー読み取りとリクエストのタイムアウト
  • アクセスログ — リクエストID、メソッド、パス、ステータス、所要時間を含む構造化 JSON アクセスログ
  • リクエストID — X-Request-ID の自動生成とパススルー
  • エラーページ — 任意の HTTP ステータスコードに対応するカスタム HTML エラーページ
  • SSE — PHP からのリアルタイム Server-Sent Events ストリーミング
  • 早期レスポンス — レスポンスを即座に送信し、バックグラウンド処理を継続
  • 非同期 Promise — PHP クロージャをバックグラウンドスレッドで実行し、結果を待機
  • デコレーター — PHP 8 の属性で関数呼び出しやメソッド呼び出しをインターセプト
  • 分散トレーシングと APM — W3C Trace Context、OpenTelemetry、自動計装、PHP トレーシング SDK
  • プロファイリング — リクエスト単位の組み込みプロファイラー: 有効化のトリガー、PHP SDK と属性、エクスポート形式、内部ルート
  • 内部サーバー — ヘルスチェック、Prometheus メトリクス、ライブ設定用の専用ポート

セキュリティ

  • ドットパスブロッキング — 隠しファイルおよびディレクトリ（.env、.git/、.htaccess）の自動ブロック
  • 信頼済みプロキシ — CIDR ベースの信頼設定により、Forwarded（RFC 7239）、X-Forwarded-*、および Cloudflare の背後では CF-Connecting-IP ヘッダーから実際のクライアント IP を抽出
  • PHP 実行拒否リスト — 書き込み可能な公開パス（例: /uploads/** や特定のレガシースクリプト）での .php 実行をブロックし、レガシーアプリへのアップロードシェル攻撃を防止
  • パスの拒否ルール — DOCUMENT_ROOT に置いた gitignore 形式の .oxphpdeny により、vendor/、ダンプ、バックアップなどのファイルが提供されないようにするか、それらへのリクエストをアプリケーションに引き渡す
  • シンボリックリンク許可パス — DOCUMENT_ROOT の外にあるシンボリックリンクのターゲットを対象とするオプトインの許可リスト。デフォルトのシンボリックリンクによる脱出防止を弱めることなく、Laravel 形式の storage:link や共有アセットボリュームをサポート

PHP

  • HTTP リクエスト API — oxphp_http_request() によるオブジェクト指向のリクエストアクセス: クエリパラメータ、パース済みボディ、ヘッダー、Cookie、ファイルアップロードなど
  • 関数 — OxPHP が提供する組み込み PHP 関数（oxphp_worker()、oxphp_request_id()、oxphp_server_info() など）
  • スーパーグローバル — $_SERVER、$_GET、$_POST、$_COOKIE、$_FILES、php://input がどのように設定されるか
  • Worker クラス — OxPHP\Server\Worker ランタイムハンドル: ワーカーのイントロスペクション、ワーカーのエントリーポイント、スレッドごとのメトリクス
  • OPcache と JIT — OPcache の設定と JIT コンパイルの設定

共有状態

プロセス全体で使える並行プリミティブにより、ワーカーは Redis、Memcached、APCu なしで可変状態を協調管理できます。すべてがプロセス内に存在するため、1 操作あたりのコストはネットワークのラウンドトリップではなくマイクロ秒単位です。

  • 概要 — レジストリモデル、ハンドルのライフサイクル、共有状態を使うべき場面
  • レジストリ — プロセス全体のレジストリ、エントリのライフサイクル、イントロスペクション
  • Counter — アトミックな int64 アキュムレーター（get、set、add、compareAndSet）
  • Atomic — 明示的なメモリオーダリング制御を備えたアトミックな int64
  • Flag — ワンショットの遷移向けのアトミックなブール値
  • Once — 再入安全なファクトリを備えた、一度だけ実行されるコンテナ
  • Mutex — デッドロック検出を備えた、格納値に対する Mutex
  • Channel — 上限付きでファイバーを認識する MPMC キュー
  • Map — バッチアクセスに対応した、文字列キーの並行ストア
  • Pool — スレッド単位のアフィニティを備えた上限付きオブジェクトプール
  • 命名規則 — Shared\* ファミリー全体のメソッド命名チートシート
  • オブザーバビリティ — Prometheus カウンターと JSON イントロスペクションエンドポイント
  • 外部ストアへの移行 — Redis や APCu へ移行するタイミングと方法

アーキテクチャ

  • アーキテクチャ概要 — OxPHP の仕組み: 非同期 HTTP 処理、PHP ワーカープール、リクエストの流れ、安全性の保証

連携

  • MCP サーバー — Model Context Protocol 経由で OxPHP のドキュメントをコーディングエージェントに接続する

サンプル

OxPHP で人気の PHP アプリケーションを動かすためのエンドツーエンドのレシピです。それぞれが Dockerfile、docker-compose.yml、インストール手順、そして標準（nginx + PHP-FPM）のドキュメントでは扱われない OxPHP 固有の注意点を含む、完結した Docker Compose プロジェクトになっています。

間違いを見つけましたか？報告する →