OxPHP ドキュメント

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

なぜ OxPHP なのか

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

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

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

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

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

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

はじめに

運用

機能

  • ルーティング — 3 つのルーティングモード: 従来のファイルマッピング、フレームワークのフロントコントローラー、SPA フォールバック。ワーカーモードはこれらと直交する実行モデルの切り替えであり、どのルーティングモードにも上乗せして適用可能
  • 静的ファイル — ファイルキャッシュ、MIME 判定、ETag/Last-Modified ヘッダー、ストリーミング
  • ワーカーモード — リクエスト間で自動的にソフトリセットされる永続的な PHP プロセス
  • ファイバー多重化 — 協調的マルチタスクにより、ワーカースレッドごとに数百件の並行リクエストを処理
  • 圧縮 — テキストベースのレスポンス向けの Brotli 圧縮
  • 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
  • 内部サーバー — ヘルスチェック、Prometheus メトリクス、ライブ設定用の専用ポート

セキュリティ

  • ドットパスブロッキング — 隠しファイルおよびディレクトリ（.env、.git/、.htaccess）の自動ブロック
  • 信頼済みプロキシ — CIDR ベースの信頼設定により、Forwarded（RFC 7239）および X-Forwarded-* ヘッダーから実際のクライアント IP を抽出
  • PHP 実行拒否リスト — 書き込み可能な公開パス（例: /uploads/** や特定のレガシースクリプト）での .php 実行をブロックし、レガシーアプリへのアップロードシェル攻撃を防止
  • シンボリックリンク許可パス — 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 がどのように設定されるか
  • 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 ワーカープール、リクエストの流れ、安全性の保証

サンプル

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

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