コマンドラインインターフェース
oxphp バイナリには 3 つの役割があります。HTTP サーバーを起動する serve、単一の PHP スクリプトを最後まで実行する run、そして config ユーティリティです。引数なしの素の oxphp は暗黙的な serve となるため、公開イメージの CMD ["oxphp"] はこれまでどおりサーバーを起動し続けます。
USAGE:
oxphp [OPTIONS]
oxphp <COMMAND> [OPTIONS]
oxphp serve [--user=<name|uid[:gid]>]
oxphp run [-d key=value]... [--user=<spec>] <script.php> [args]...
oxphp [-d key=value]... [--user=<spec>] <script.php> [args]...
OPTIONS:
-h, --help Print this help and exit
-v, --version Print version information and exit
COMMANDS:
serve Start the HTTP server (default; same as bare 'oxphp')
run Execute a single PHP script under CLI semantics and exit
config Configuration utilities (see 'oxphp config --help')役割はキーワードによって選択されます。serve、run、config という正確なトークンがサブコマンドを選び、それ以外の最初の位置引数はスクリプトパスとして扱われます。したがって oxphp ./bin/migrate.php は oxphp run ./bin/migrate.php の省略形です。拡張子によるヒューリスティックはありません。PHP はファイルの内容によって実行されるため、拡張子のないスクリプトも実行されます。ファイルが存在しない場合は、php とまったく同じようにファイルシステムから報告されます。
oxphp serve
HTTP アプリケーションサーバーを起動します。これがデフォルトの役割です。oxphp と oxphp serve は等価です。設定は環境変数を介して行い、serve 自体は --user のみを受け取ります。
oxphp # implicit serve — best-effort drop to www-data
oxphp serve # explicit — same default
oxphp serve --user=appuser # drop to a specific user (fail-fast)
oxphp serve --user=root # opt out: keep running as rootデフォルトでは、--user を指定しない場合、serve は www-data へのベストエフォートな降格を行います。root として起動され、かつ www-data アカウントが存在する場合(公式イメージがそうです)、root としてリスナーをバインドしてから、トラフィックの処理が始まる前に恒久的に www-data へ降格します。非 root として起動された場合は現在のユーザーを維持します。www-data アカウントが存在しないホスト上で root として起動された場合は、警告をログに出力して root のまま続行します。このデフォルトの挙動が起動を中断させることはありません。
--user=<spec> はターゲットを上書きし、fail-fast(早期失敗)です。root としてバインドしてからそのユーザーへ恒久的に降格し、root として起動されていない場合はエラーで終了します。意図的に root を維持したい場合は --user=root を渡してください。完全なパターン、<spec> の文法、ファイルパーミッションのチェックリストについては、ポート 80 で非 root として実行するを参照してください。
oxphp run
oxphp run <script.php> [args…] は単一の PHP ファイルを最後まで実行し、スクリプト自身の終了コードで終了します。これはメインスレッド上で動作し、リスナーもワーカープールもリクエストキューもありません。PHP_SAPI === 'cli' となり、phpinfo() は HTML ではなくテキストを出力するため、標準の php CLI と一致します。
oxphp run migrate.php
oxphp run bin/console.php cache:clear
oxphp run -d memory_limit=512M import.php data.csvこれはマイグレーション、cron ジョブ、キューコンシューマー、そして artisan / console スタイルのコマンドを、アプリケーションを配信するのと同じイメージ内で、2 つ目の PHP をインストールすることなく実行するための役割です。
スクリプトの下では OxPHP エンジンの全機能が利用できます。ファイバー(oxphp_sleep())と共有状態(OxPHP\Shared\*)はそのまま動作します。非同期 Promise(oxphp_async())は ASYNC_WORKERS が 0 より大きい場合に動作します。デフォルトの呼び出しでは非同期プールを起動しないため、バックグラウンドランタイムも存在しません。
$argv と $argc は設定され($argv[0] はスクリプトパス)、STDIN / STDOUT / STDERR も定義されるため、Composer 系や Symfony Console 系のエントリーポイントは変更なしで動作します。
スクリプトパスより後ろのすべてのトークンは、-- 接頭辞付きのものも含めて、そのまま PHP に渡されます。したがって通常の引数には明示的な -- は不要です。oxphp 自身に向けたフラグ(-d、--user)はスクリプトパスの前に置かなければなりません。それより後ろにあるものはすべてスクリプトのものです。
oxphp run console.php migrate --force --pretend
# ▲ script └──────────────┬──────────┘
# $argv[1..], passed to PHP verbatim (oxphp parses nothing here)したがって oxphp run console.php --force はスクリプトの $argv に --force を渡しますが、oxphp run --force console.php はエラーになります。--force がスクリプトパスより前にあり、そこで oxphp は -d / --user / --help しか受け付けないためです。
-- オプション終端マーカー
oxphp は標準の -- オプション終端マーカーを尊重します。これが意味を持つのはちょうど 1 か所だけです。スクリプトパスの前で、スクリプトパス自体がダッシュで始まる場合です。-- はオプションのパースを停止させるため、次のトークンがスクリプトパスとして扱われ、oxphp がそれを消費します。これは PHP には転送されません。
oxphp run -- -odd-name.php # runs the script "-odd-name.php"
oxphp -- -odd-name.php # same, implicit form
oxphp run -odd-name.php # error: parsed as options → "unexpected argument to 'run': -o"スクリプトパスより後ろには終端すべきオプションがもう残っていないため、そこにある -- は通常のデータとなり、php とまったく同じように、そのまま PHP に渡されます。
oxphp run app.php -- --raw # $argv = ["app.php", "--", "--raw"]shebang スクリプト
先頭の #! 行はコンパイル前にスキップされるため、oxphp の shebang を持つ実行可能な拡張子なしスクリプトはそのまま実行できます。
#!/usr/bin/env oxphp
<?php
echo "hello from a shebang script\n";chmod +x ./greet
./greet-d ini オーバーライド
-d key[=value] はこの実行に対して php.ini ディレクティブを設定します。繰り返し指定でき、値のない -d key は値を "1" に設定します。これらのオーバーライドはモジュール起動前に適用されるため、あらゆる型のディレクティブについて php.ini より優先されます。これには、実行時の ini_set() では変更できない PHP_INI_SYSTEM / PHP_INI_PERDIR ディレクティブ(opcache.*、register_argc_argv など)も含まれます。
oxphp run -d memory_limit=1G -d display_errors=1 report.phprun のデフォルト ini
run の役割は、あなたの -d オーバーライドや php.ini より前に、CLI 向けのデフォルトを適用します。
| Directive | Default | Why |
|---|---|---|
max_execution_time |
0 |
一度きりのジョブ(マイグレーション、インポーター、デーモン)は SIGALRM によって停止させられてはなりません。 |
max_input_time |
-1 |
CLI には入力パースの締め切りはありません。 |
display_errors |
stderr |
エラーは標準出力ではなく標準エラーへ出力されます。 |
html_errors |
0 |
端末向けのプレーンテキストエラーです。 |
output_buffering |
0 |
出力は生成されるそばから書き出されます。 |
implicit_flush |
1 |
各書き込みは即座にフラッシュされます。 |
register_argc_argv |
1 |
$argv / $argc が利用可能になります。 |
スーパーグローバルは run では常に有効です。一度きりのスクリプトには $argv、$_SERVER、$_ENV が必要だからです。これは HTTP サーバーに適用される SUPERGLOBALS_ENABLED トグルとは無関係に成り立ちます。
終了コード
| Code | Meaning |
|---|---|
| script's own | exit($code) / die($code)、または正常終了時は 0。 |
255 |
致命的エラー、キャッチされない例外、またはパースエラー。 |
1 |
スクリプトパスを開けませんでした(oxphp: Could not open input file: <path>)。 |
2 |
無効な -d 引数。 |
ファイルを開けないケースはエンジン起動前にチェックされるため、存在しないスクリプトや読み取れないスクリプトは、エンジンを立ち上げてコンパイルエラーで落ちるのではなく、php スタイルのメッセージで即座に失敗します。
run パスでの --user
run は serve と同じデフォルトに従います。--user を指定しない場合、スクリプトの実行前に www-data へのベストエフォートな降格を行います(すでに非 root の場合は静かにスキップされます)。oxphp run --user=<spec> <script.php> はターゲットを上書きするため、root として起動された一度きりのジョブを特定の非特権ユーザーとして実行できます。--user=root は root を維持します。<spec> の文法と降格の仕組みは serve --user と同一です。非 root として起動された状態で明示的な --user を指定すると、それは致命的エラーになります。
oxphp config
設定ユーティリティです。--check は環境変数による設定を検証し、サーバーを起動せずに問題を報告します。
oxphp config --checkconfig: OKこのチェックが対象とするのはファイルシステムの健全性のみです。すなわちパスの存在と、ファイル/ディレクトリの種別(DOCUMENT_ROOT、ENTRY_FILE、TLS_CERT、TLS_KEY、ERROR_PAGES_DIR など)です。PHP ランタイム、TLS ハンドシェイク、ネットワークバインドは対象外です。失敗した場合は非ゼロで終了し、問題 1 件につき 1 行で config: INVALID を出力します。
oxphp config --check は無効な設定に対して非ゼロで終了するため、エントリーポイントや CI ジョブにおける起動前ゲートとして機能します。
--help と --version
oxphp --help # full usage
oxphp config --help # config subcommand usage
oxphp --version # version and the feature flags compiled into this binaryoxphp --version はそのビルドで有効になっている機能(例えば php, plugin-apm, plugin-async)を報告します。これは、あるイメージが APM、async、その他のオプションプラグインを組み込んでビルドされているかを確認する最も手早い方法です。
次のステップ
- 設定リファレンス: サーバーが読み取るすべての環境変数。
- ポート 80 で非 root として実行する: 完全な
--userパターン、<spec>の文法、ファイルパーミッションのチェックリスト。 - スーパーグローバル:
runが一度きりのスクリプトのために常に設定するもの。