インストール

OxPHP は Docker イメージとして配布されており、PHP アプリケーションの配信を始めるうえで最速かつ推奨される方法です。このイメージには、サーバーバイナリ、PHP 8.4 または 8.5 ZTS、OxPHP 拡張、そして Alpine Linux 上のすべてのランタイム依存関係が同梱されています。デフォルトの :0.10.0 および :latest タグには PHP 8.5 が含まれます。PHP 8.4 を取得するには、:0.10.0-php8.4、:php8.4、または任意の *-php8.4* タグバリアントを使用してください。

Docker（推奨）

GitHub Container Registry から公式イメージを取得します。

bash
docker pull ghcr.io/oxphp/oxphp:0.10.0

このイメージには以下が含まれます。

  • OxPHP サーバーバイナリ — 非同期 HTTP サーバー
  • PHP ZTS ランタイム — 取得したタグに応じて 8.4 または 8.5。マルチワーカー実行のためのスレッドセーフな PHP
  • OxPHP PHP 拡張（oxphp_sapi.so） — oxphp_request_id()、oxphp_server_info()、oxphp_worker() などの組み込み関数を提供します
  • ブリッジライブラリ（liboxphp_bridge.so） — Rust サーバーと PHP ランタイムを接続します
  • Alpine Linux ベース — 最小限のランタイムフットプリント
  • USER ディレクティブなし — このイメージは特権ポートをバインドできるように root として 起動 します（nginx:alpine / php-fpm:alpine / frankenphp:alpine と同様）。ただし oxphp serve/run は配信を開始する前にデフォルトで www-data へ降格するため、トラフィックが最初から root として処理されることはありません。www-data ユーザー（UID 82、GID 82）はあらかじめ作成されており、ビルド時に /var/www/html の所有者がこのユーザーに変更されます。特定の uid を指定したい場合や多層防御を強化したい場合は、オーケストレーターのレベルでランタイムの実行 ID を明示的に固定してください。
    • docker run --user www-data ghcr.io/oxphp/oxphp:0.10.0
    • Compose: services.app.user: www-data
    • Kubernetes: securityContext.runAsUser: 82

イメージ構造

ランタイムイメージのファイルレイアウト:

text
/usr/local/ ├── bin/ │ └── oxphp # server binary ├── lib/ │ ├── libphp.so # PHP ZTS runtime (8.4 or 8.5, matches the image tag) │ ├── liboxphp_bridge.so # C bridge library │ └── php/extensions/no-debug-zts-<ABI>/ │ └── oxphp_sapi.so # OxPHP PHP extension ├── etc/php/ │ └── conf.d/ │ ├── custom.ini # PHP settings for OxPHP │ └── oxphp.ini # extension=oxphp_sapi.so
Note

<ABI> の値は PHP のマイナーバージョンによって異なります。 PHP 8.4 は 20240924 を使用し、PHP 8.5 は別の日付スタンプを使用します。以下の例が 20240924 を固定しているのは、FROM 行が php:8.4-zts-alpine3.23 を対象としているためです。FROM を切り替える場合は、日付も切り替える必要があります。ビルド内で移植性のある形で導出するには:

bash
php -r 'echo ini_get("extension_dir");' # /usr/local/lib/php/extensions/no-debug-zts-20240924

ハードコーディングを避けるため、シェルコマンド内では $(php -r 'echo ini_get("extension_dir");') を使用してください。

OxPHP の 3 つのコンポーネントとその目的:

コンポーネント サイズ 目的
oxphp 約 8 MB HTTP サーバー、ルーティング、プラグイン、メトリクス
liboxphp_bridge.so 約 50 KB サーバーを PHP ランタイムに接続する共有ブリッジライブラリ
oxphp_sapi.so 約 200 KB PHP 関数（oxphp_request_id()、OxPHP\Http\Request など）

依存関係チェーン:

graph LR
  oxphp["oxphp"] --> libphp["libphp.so"]
  libphp --> deps["libxml2, libcurl, libsqlite3, libonig, ..."]
  oxphp --> bridge["liboxphp_bridge.so"]
  sapi["oxphp_sapi.so"] --> bridge

oxphp バイナリは libphp.so と liboxphp_bridge.so にリンクします。PHP 拡張 oxphp_sapi.so もブリッジライブラリにリンクしており、これによりリクエストごとの状態が PHP コードから利用できるようになります。

最小構成の Dockerfile

ベースイメージ php:8.4-zts-alpine3.23（または php:8.5-zts-alpine3.23）には、libphp.so とそのすべての依存関係がすでに含まれています。FROM の PHP マイナーバージョンは、コピー元の OxPHP タグに合わせてください。コピーが必要なのは 3 つの OxPHP 成果物だけです。

Dockerfile
FROM php:8.4-zts-alpine3.23 COPY --from=ghcr.io/oxphp/oxphp:0.10.0 /usr/local/bin/oxphp /usr/local/bin/oxphp COPY --from=ghcr.io/oxphp/oxphp:0.10.0 /usr/local/lib/liboxphp_bridge.so /usr/local/lib/ COPY --from=ghcr.io/oxphp/oxphp:0.10.0 /usr/local/lib/php/extensions/no-debug-zts-20240924/oxphp_sapi.so /usr/local/lib/php/extensions/no-debug-zts-20240924/ RUN echo "extension=oxphp_sapi.so" > /usr/local/etc/php/conf.d/oxphp.ini COPY --chown=www-data:www-data . /var/www/html/public EXPOSE 80 443 CMD ["oxphp"]

この方法は開発に便利です。PHP CLI、composer、docker-php-ext-install、xdebug がすべて利用できます。詳細は Docker ガイド を参照してください。

本番用の Dockerfile

公式の OxPHP イメージは最小構成であり、PHP CLI や拡張のビルドツールは含まれていません。追加の PHP 拡張が必要かどうかによって、次の 2 つのビルドのどちらを選ぶかが決まります。

アプリケーションが追加の拡張（pdo_mysql、intl など）を必要とする場合は、別のステージでビルドし、最終イメージにコピーします。

Dockerfile
# Extension build stage FROM php:8.4-zts-alpine3.23 AS extensions RUN apk add --no-cache icu-dev postgresql-dev \ && docker-php-ext-install pdo pdo_mysql pdo_pgsql intl # Production FROM ghcr.io/oxphp/oxphp:0.10.0 # Runtime dependencies for extensions USER root RUN apk add --no-cache icu-libs libpq # Copy compiled extensions COPY --from=extensions /usr/local/lib/php/extensions/no-debug-zts-20240924/*.so /usr/local/lib/php/extensions/no-debug-zts-20240924/ # Enable extensions RUN { \ echo "extension=pdo.so"; \ echo "extension=pdo_mysql.so"; \ echo "extension=pdo_pgsql.so"; \ echo "extension=intl.so"; \ } > /usr/local/etc/php/conf.d/app-extensions.ini USER www-data COPY --chown=www-data:www-data . /var/www/html/public

ビルドして実行します。

bash
docker build -t my-app . docker run -p 80:80 my-app

サーバーはデフォルトでポート 80 をリッスンします。ドキュメントルートは /var/www/html/public で、上記のスニペットはプロジェクトをそこへ直接コピーしています。すでに public/ サブディレクトリを持つ Laravel、Symfony、その他のフレームワークでは、代わりに COPY --chown=www-data:www-data . /var/www/html を使用し、フレームワーク自身の public/ がデフォルトと一致するようにしてください。構成がさらに異なる場合は、DOCUMENT_ROOT 環境変数でドキュメントルートを上書きしてください。

ソースビルド（PHP なし）

PHP 機能を無効にして OxPHP をソースからビルドすると、静的ファイルのみを配信できます。

bash
cargo build --release --no-default-features

バイナリは target/release/oxphp にあります。このモードでは、静的ファイルは通常どおり配信しつつ、PHP リクエストにはプレースホルダーレスポンスを返すスタブエグゼキュータが使用されます。PHP ランタイムが存在しない状態でサーバーをテストするのに便利です。

ソースビルド（PHP あり）

完全な PHP サポートを備えた OxPHP をビルドするには、まずブリッジライブラリと PHP 拡張をコンパイルしてインストールする必要があります。

前提条件

  • Rust ツールチェーン（1.91.1 以降）
  • ZTS（Zend Thread Safety）を有効にした PHP 8.4 または 8.5
  • C コンパイラ（gcc または clang）
  • phpize と PHP 開発ヘッダー

ビルド手順

  1. ブリッジライブラリをビルドしてインストールします。

    bash
    cd ext/bridge make && sudo make install

  2. PHP 拡張をビルドしてインストールします。

    bash
    cd ../ phpize && ./configure --enable-oxphp-sapi && make && sudo make install

  3. OxPHP をビルドします。 デフォルトの機能には php が含まれます。

    bash
    cargo build --release

このバイナリは、実行時にライブラリ検索パス上の共有ライブラリを必要とします。

bash
export LD_LIBRARY_PATH=/usr/local/lib ./target/release/oxphp
Note

Alpine Linux にデプロイする場合は、PHP ランタイムに使用するのと同じ php:{8.4,8.5}-zts-alpine イメージ内でビルドしてください。出荷する OxPHP イメージのマイナーバージョンに合わせます。glibc と musl のビルドを混在させると、実行時エラーが発生します。公式の Docker イメージはこれを正しく処理します。

インストールの確認

OxPHP を起動すると、構造化された JSON ログ出力によってサーバーが稼働していることを確認できます。

text
{"timestamp":"...","level":"INFO","message":"OxPHP HTTP server starting","listen_addr":"0.0.0.0:80",...} {"timestamp":"...","level":"INFO","message":"Server listening","addr":"0.0.0.0:80"}

サーバーが応答することをテストします。

bash
curl http://localhost/

INTERNAL_ADDR で内部サーバーを有効にした場合は、ヘルスエンドポイントを確認します。

bash
curl http://localhost:9090/health

正常なサーバーは 200 と JSON ステータスを返します。劣化したサーバーは 503 を返します。

次のステップ

  • クイックスタート — プロジェクトを作成し、Docker Compose で OxPHP を実行して、最初のリクエストを送ります
  • Docker ガイド — 開発用と本番用の Dockerfile、Compose の設定、ボリュームマウント
  • 設定 — 環境変数の完全なリファレンス
間違いを見つけましたか？報告する →