PHP関数

OxPHPは oxphp_sapi 拡張を通じて関数を登録します。この拡張は、サーバーが実行するすべてのPHPスクリプトに対して自動的にロードされます。extension= ディレクティブも手動でのロードも必要ありません。ここに列挙されているすべての関数は、PHPコードの1行目から利用できます。

目次

oxphp_http_request()

php
oxphp_http_request(): \OxPHP\Http\Request

現在のHTTPリクエストに対応するリクエストオブジェクトを返します。このオブジェクトは、HTTPメソッド、URI、クエリパラメーター、パース済みのボディ、ヘッダー、クッキー、アップロードされたファイル、クライアントIP、リクエストのタイミングに対して型付きのアクセスを提供します。

戻り値: 現在のPHPワーカースレッド内のリクエストデータに支えられた \OxPHP\Http\Request インスタンス。

スローする例外: アクティブなリクエストの外部で呼び出された場合、OxPHP\Http\Exception 名前空間の例外がスローされます。

例外 状況
\OxPHP\Http\Exception\WorkerIdleException ワーカーモードで、リクエストとリクエストの間
\OxPHP\Http\Exception\AsyncContextException oxphp_async() のコールバック内
\OxPHP\Http\Exception\NoActiveRequestException アクティブなリクエストがないその他の任意のコンテキスト

通常のリクエスト処理コードでは、例外処理は必要ありません。

例:

php
<?php $request = oxphp_http_request(); $method = $request->method(); // "POST" $path = $request->path(); // "/api/users" $email = $request->payload('email'); // from JSON or form body $token = $request->header('Authorization'); $theme = $request->cookie('theme', 'light');

完全なインターフェースリファレンスについては、HTTP Request API のドキュメントを参照してください。

oxphp_superglobals_enabled()

php
oxphp_superglobals_enabled(): bool

このサーバーインスタンスでスーパーグローバルの生成が有効になっているかどうかを返します。この値は SUPERGLOBALS_ENABLED 環境変数を反映しており、サーバーの稼働中に変化することはありません。

false の場合、$_GET、$_POST、$_COOKIE、$_FILES、$_SERVER は空の配列になります。HTTP Object API（oxphp_http_request()）、php://input、およびPHPのセッション関数は影響を受けません。

戻り値: SUPERGLOBALS_ENABLED が true（デフォルト）のとき true、それ以外のとき false。

例:

php
<?php if (oxphp_superglobals_enabled()) { $query = $_GET['page'] ?? 1; } else { $query = oxphp_http_request()->query('page', 1); }

oxphp_request_id()

php
oxphp_request_id(): string

現在のリクエストの一意なリクエスト識別子を返します。これは X-Request-ID レスポンスヘッダーで送信される値と同じものです。クライアントが X-Request-ID ヘッダーを送信した場合、OxPHPは新しいIDを生成する代わりに、それをそのまま通します。

戻り値: OxPHPがIDを生成する場合は20文字の16進数文字列（例: "67890abc12341a2b0042"）。クライアントが X-Request-ID ヘッダーを送信した場合は、その値がそのまま返されます（1〜64文字、英数字に加えて -、_、.）。

例:

php
<?php $id = oxphp_request_id(); error_log("[$id] Processing order #1234"); // Propagate the ID to downstream services header("X-Correlation-ID: $id");

oxphp_worker_id()

php
oxphp_worker_id(): int

現在のリクエストを処理しているPHPワーカースレッドの、ゼロ始まりのインデックスを返します。ワーカーのインデックスは 0 から PHP_WORKERS - 1 までの範囲です。

戻り値: 現在のワーカースレッドを識別する整数。

例:

php
<?php $workerId = oxphp_worker_id(); // Use per-worker temp files to avoid collisions $tmp = "/tmp/worker_{$workerId}_buffer.dat"; error_log("Worker $workerId handling request");

oxphp_server_info()

php
oxphp_server_info(): array

サーバーとリクエストのメタデータを含む連想配列を返します。

戻り値: 以下のキーを持つ配列。

キー 型 説明
version string サーバーのバージョン（例: "0.10.0"）
worker_id int oxphp_worker_id() と同じ値
request_time float リクエストが開始したときのマイクロ秒精度のUnixタイムスタンプ
worker_mode bool 現在のプロセスがワーカーモードで実行されているかどうか

例:

php
<?php $info = oxphp_server_info(); // [ // "version" => "0.10.0", // "worker_id" => 3, // "request_time" => 1738800000.123456, // "worker_mode" => true, // ] $elapsed = microtime(true) - $info['request_time']; echo "Processing took {$elapsed}s so far";

oxphp_finish_request()

php
oxphp_finish_request(): bool

レスポンスをクライアントにフラッシュし、PHPの実行をバックグラウンドで続行します。クライアントは完全なHTTPレスポンスを即座に受け取り、スクリプトは自然に終了するまで動作し続けます。これはPHP-FPMにおける fastcgi_finish_request() に相当するOxPHPの機能です。

戻り値: 成功時は true、このリクエストで既に呼び出されている場合は false。

Note

スクリプトが終了するまで、PHPワーカースレッドは占有されたままになります。バックグラウンド処理は短く保つか、重い処理はキューにオフロードしてください。

例:

php
<?php http_response_code(202); echo json_encode(['status' => 'accepted']); oxphp_finish_request(); // The client already has its 202 response; continue working send_notification_email($user); update_analytics($event);

oxphp_is_worker()

php
oxphp_is_worker(): bool

サーバーがワーカーモードで実行されているかどうかを返します。ワーカーモードは WORKER_MODE_ENABLED=true のときに有効になります。

戻り値: ワーカーモードで実行されている場合は true、従来モードの場合は false。

例:

php
<?php if (oxphp_is_worker()) { // Reuse persistent connections across requests $db = $GLOBALS['db'] ??= new PDO($dsn); } else { // Traditional mode: create a new connection per request $db = new PDO($dsn); }

oxphp_worker()

php
oxphp_worker(callable $handler): bool

永続的なワーカーモードのループに入ります。OxPHPは受信するHTTPリクエストごとに $handler を1回呼び出します。リクエストとリクエストの間には、ソフトリセットによってリクエスト単位の状態（出力バッファー、ヘッダー、スーパーグローバル）がクリアされますが、PHPのヒープは破棄されません。そのため、ハンドラーの外側で宣言された変数は、リクエストをまたいで保持されます。

パラメーター:

  • $handler — リクエストごとに1回呼び出されます。ハンドラーは引数を受け取りません。ハンドラー内でリクエストデータにアクセスするには、スーパーグローバル（$_SERVER、$_GET、$_POST など）または oxphp_http_request() を使用してください。

戻り値: グレースフルシャットダウン時は true、ワーカーモードでない場合は false。

ワーカーループは、以下のいずれかの条件が満たされたときに終了します。

  • サーバーがグレースフルにシャットダウンする
  • ハンドラーが3回連続でキャッチされない例外または致命的エラーを発生させる
  • ワーカーが WORKER_MAX_MEMORY_MIB を超過する
  • アプリケーションが Worker::scheduleExit() を呼び出す
Note

oxphp_worker() はワーカーモード（WORKER_MODE_ENABLED=true）でのみ機能します。従来モードでは警告をログに記録し、false を返します。

例:

worker.php
<?php // worker.php — runs once per worker process lifetime // Bootstrap: executed once on startup require __DIR__ . '/vendor/autoload.php'; $app = new App(); // Handle requests in a loop oxphp_worker(function () use ($app) { $app->handle(); }); // Code after oxphp_worker() runs during shutdown $app->terminate();

oxphp_is_streaming()

php
oxphp_is_streaming(): bool

現在のリクエストがストリーミングモードかどうかを返します。ストリーミングモードは、oxphp_stream_flush() が最初に呼び出されたとき、またはPHPが Content-Type: text/event-stream を設定したときに自動的に有効になります。

戻り値: ストリーミングモードがアクティブな場合は true、それ以外の場合は false。

例:

php
<?php if (oxphp_is_streaming()) { echo "data: " . json_encode($event) . "\n\n"; oxphp_stream_flush(); } else { echo json_encode($allData); }

oxphp_stream_flush()

php
oxphp_stream_flush(): bool

ストリーミングモードを有効にし、バッファーされた出力をHTTPチャンクとしてクライアントにフラッシュします。最初の呼び出しではHTTPヘッダーが即座に送信され、ストリーミングが開始されます。それ以降の各呼び出しでは、前回のフラッシュ以降に書き込まれた出力がフラッシュされます。

戻り値: 成功時は true、oxphp_finish_request() が既に呼び出されている場合は false。

Note

ストリーミングモードは、PHPが Content-Type: text/event-stream を設定したときにも自動的に有効になります。その場合はPHP組み込みの flush() を使用できますが、PHPの出力バッファリング層をバイパスするために、まず ob_end_flush() を呼び出してください。

例:

php
<?php header('Content-Type: text/event-stream'); header('Cache-Control: no-cache'); for ($i = 0; $i < 10; $i++) { echo "id: $i\n"; echo "data: " . json_encode(['counter' => $i]) . "\n\n"; oxphp_stream_flush(); oxphp_sleep(1.0); // use oxphp_sleep instead of sleep — does not block the worker in fiber mode }

oxphp_sleep()

php
oxphp_sleep(float $seconds): void

指定された時間だけスリープします。ファイバー内で実行されているワーカーモードのハンドラー内では、この呼び出しは協調的に動作します。つまり、現在のファイバーをサスペンドし、待機中に他のリクエストを処理できるようにします。ファイバーの外側では、標準的なブロッキングの usleep() にフォールバックします。

パラメーター:

  • $seconds — スリープする時間（秒）。小数値も受け付けます（例: 500ミリ秒なら 0.5）。0 以下の値は即座に戻ります。

戻り値: void

例:

php
<?php oxphp_worker(function () { // In worker mode with fiber multiplexing: // this suspends the fiber rather than blocking the thread oxphp_sleep(1.0); echo json_encode(['done' => true]); });

oxphp_usleep()

php
oxphp_usleep(int $microseconds): void

指定されたマイクロ秒数だけスリープします。oxphp_sleep() と同様に、ファイバー内では協調的に動作し、それ以外の場合はブロッキングの usleep() にフォールバックします。

パラメーター:

  • $microseconds — スリープする時間（マイクロ秒）。0 以下の値は即座に戻ります。

戻り値: void

例:

php
<?php oxphp_worker(function () { // Poll for a condition every 100ms without blocking other requests while (!$condition_met()) { oxphp_usleep(100_000); } echo "ready"; });

oxphp_async()

php
oxphp_async(Closure $closure, mixed ...$args): int

クロージャを専用の非同期ワーカースレッドで実行するようにディスパッチし、Promise IDを即座に返します。呼び出し元はクロージャの完了を待たずに実行を続けます。結果を取得するには oxphp_async_await() を使用してください。

パラメーター:

  • $closure — 非同期ワーカースレッドで実行する、ユーザー定義の Closure
  • ...$args — クロージャに渡す引数。スカラー値（null、bool、int、float、string）、それらの配列、および OxPHP\Shared\* インスタンス（スレッド境界を越えられる唯一のオブジェクト）を受け付けます。リソースおよび Shared 以外のオブジェクトは拒否されます。

戻り値: 整数のPromise ID。これを oxphp_async_await()、oxphp_async_await_all()、oxphp_async_await_race()、または oxphp_async_await_any() に渡します。

スローする例外: 以下のケースで OxPHP\Async\AsyncException がスローされます。

  • 非同期プールが無効化されている（ASYNC_WORKERS=0）— メッセージ: "Async pool is disabled. Set ASYNC_WORKERS > 0 to enable."
  • クロージャがユーザー定義でない
  • 非同期プールが満杯（すべてのキュースロットが占有されている）
  • 引数または use 変数がオブジェクトまたはリソースを含んでいる
Note

クロージャ内で use を介してキャプチャされたuse変数も同じ制約に従います。オブジェクトとリソースは拒否されます。

例:

php
<?php // Dispatch two independent tasks concurrently $p1 = oxphp_async(function () { return fetch_from_api('/users'); }); $p2 = oxphp_async(function () { return fetch_from_api('/posts'); }); // Retrieve both results $users = oxphp_async_await($p1); $posts = oxphp_async_await($p2);

oxphp_async_await()

php
oxphp_async_await(int $promise_id, float $timeout = 0.0): mixed

指定された非同期Promiseが完了するまでブロックし、その結果を返します。ワーカーモードのファイバー内では、スレッドをブロックする代わりに、現在のファイバーを協調的にサスペンドします。

パラメーター:

  • $promise_id — oxphp_async() が返したPromise ID
  • $timeout — 待機する最大秒数。0.0 は無期限に待機することを意味します。デフォルト: 0.0

戻り値: 非同期クロージャの戻り値。

スローする例外:

  • OxPHP\Async\AsyncException — 非同期プールが無効化されている（ASYNC_WORKERS=0）場合、または非同期タスクが例外をスローした場合
  • OxPHP\Async\TimeoutException — $timeout を超過した場合

例:

php
<?php $promise = oxphp_async(function (int $n) { return array_sum(range(1, $n)); }, 1_000_000); $result = oxphp_async_await($promise); echo $result; // 500000500000 // With timeout try { $result = oxphp_async_await($promise, 5.0); } catch (\OxPHP\Async\TimeoutException $e) { echo "Task took too long"; }

oxphp_async_await_all()

php
oxphp_async_await_all(array $promise_ids, float $timeout = 0.0): array

配列内のすべてのPromiseをawaitし、各Promise IDをその結果にマッピングした連想配列を返します。Promiseは配列の順序でawaitされます。

パラメーター:

  • $promise_ids — oxphp_async() が返した整数のPromise IDの配列
  • $timeout — Promiseごとに待機する最大秒数。0.0 は無期限に待機することを意味します。デフォルト: 0.0

戻り値: 各キーがPromise ID（整数）で、各値がそのPromiseの結果となる連想配列。

スローする例外:

  • OxPHP\Async\AsyncException — 非同期プールが無効化されている（ASYNC_WORKERS=0）場合、またはいずれかのPromiseが失敗した場合
  • OxPHP\Async\TimeoutException — いずれかのPromiseが $timeout を超過した場合

例:

php
<?php $promises = [ oxphp_async(fn() => slow_query('users')), oxphp_async(fn() => slow_query('orders')), oxphp_async(fn() => slow_query('products')), ]; $results = oxphp_async_await_all($promises); foreach ($results as $promiseId => $result) { // process $result }

oxphp_async_await_race()

php
oxphp_async_await_race(array $promise_ids, float $timeout = 0.0): array

複数のPromiseを競争させ、最初に決着したもの（fulfillでもrejectでも）を返します。他のPromiseはキャンセルされず、実行を続け、oxphp_async_await() でawait可能なまま残ります。これはJavaScriptの Promise.race に相当します。

パラメーター:

  • $promise_ids — oxphp_async() が返した、少なくとも1つの整数のPromise IDの配列。空であってはなりません。
  • $timeout — いずれかのPromiseが決着するまで待機する最大秒数。0.0 は無期限に待機することを意味します。デフォルト: 0.0

戻り値: 2つのキーを持つ連想配列。

  • id（int）— 勝者のPromise ID
  • value（mixed）— 勝ったPromiseの戻り値

スローする例外:

  • OxPHP\Async\AsyncException — 非同期プールが無効化されている（ASYNC_WORKERS=0）場合、または勝ったPromiseがrejectされた場合
  • OxPHP\Async\TimeoutException — $timeout 以内にどのPromiseも決着しなかった場合

例:

php
<?php // Try two mirror endpoints; use whichever responds first $p1 = oxphp_async(fn() => fetch('https://mirror-1.example.com/data')); $p2 = oxphp_async(fn() => fetch('https://mirror-2.example.com/data')); $winner = oxphp_async_await_race([$p1, $p2], timeout: 10.0); echo "Mirror {$winner['id']} won: " . json_encode($winner['value']);

oxphp_async_await_any()

php
oxphp_async_await_any(array $promise_ids, float $timeout = 0.0): array

1つのPromiseがFULFILLされ次第すぐに戻ります。rejectは蓄積され、すべてのPromiseがrejectされた場合にのみ観測可能になります。これはJavaScriptの Promise.any に相当します。動作するソースであればどれでもよいという、フォールバック／冗長化パターンに便利です。

パラメーター:

  • $promise_ids — oxphp_async() が返した、少なくとも1つの整数のPromise IDの配列。空であってはなりません。
  • $timeout — 最初のfulfillmentまで待機する最大秒数。0.0 は無期限に待機することを意味します。デフォルト: 0.0

戻り値: 2つのキーを持つ連想配列。

  • id（int）— 最初にfulfillされたPromiseのPromise ID
  • value（mixed）— 勝ったPromiseの戻り値

スローする例外:

  • OxPHP\Async\AsyncException — 非同期プールが無効化されている（ASYNC_WORKERS=0）場合
  • OxPHP\Async\AggregateAsyncException — すべてのPromiseがrejectされた場合。この例外は、getErrors()（位置ベース、0..N-1のキー）、getErrorMap()（idをキーとする）、getPromiseIds() を介してすべてのエラーを保持します。
  • OxPHP\Async\TimeoutException — $timeout 以内にどのPromiseもfulfillされなかった場合。getPartialErrors() は締め切り前に既にrejectされたPromiseを列挙し、getCancelledPromiseIds() はまだ決着しておらず、そのためキャンセルされたPromiseを列挙します。それらのキャンセルフラグが設定され、レシーバーが破棄されます — その後これらのidのいずれかを oxphp_async_await*() に渡すと "unknown or already-awaited promise id" がスローされます。このリストは監査証跡であり、再開可能な作業のキューではありません。

動作:

  • 勝敗が決した時点でまだ保留中だったPromiseは、oxphp_async_await() で個別にawaitできるまま残ります。
  • 勝者より前に既にrejectされたPromiseはawaitできません。それらの結果は、候補エラーとして蓄積された時点で消費されています。

例:

php
<?php $mirror_a = oxphp_async(fn() => fetch('https://mirror-a.example.com/data')); $mirror_b = oxphp_async(fn() => fetch('https://mirror-b.example.com/data')); $mirror_c = oxphp_async(fn() => fetch('https://mirror-c.example.com/data')); try { $winner = oxphp_async_await_any([$mirror_a, $mirror_b, $mirror_c], 5.0); echo "Mirror {$winner['id']} responded: " . json_encode($winner['value']); } catch (\OxPHP\Async\AggregateAsyncException $e) { // every mirror rejected foreach ($e->getErrorMap() as $promise_id => $err) { error_log("mirror {$promise_id}: " . $err->getMessage()); } } catch (\OxPHP\Async\TimeoutException $e) { // deadline elapsed before any mirror fulfilled $partial = $e->getPartialErrors(); $cancelled = $e->getCancelledPromiseIds(); }

oxphp_register_decorator()

php
oxphp_register_decorator(string $class): bool

関数呼び出しやメソッド呼び出しをラップするデコレーターとして、PHPクラスを登録します。このクラスは OxPHP\Decorator\AttributeInterface を実装している必要があります。登録されると、OxPHPはデコレーターの #[Attribute] ターゲットに一致するすべての関数呼び出しまたはメソッド呼び出しの前後で、デコレーターの before() および after() フックを呼び出します。

パラメーター:

  • $class — 登録するデコレーターの完全修飾クラス名

戻り値: 成功時は true、クラスが存在しない場合、または OxPHP\Decorator\AttributeInterface を実装していない場合は false。

例:

php
<?php use OxPHP\Decorator\AttributeInterface; use OxPHP\Decorator\Context; #[\Attribute(\Attribute::TARGET_METHOD)] class LogDecorator implements AttributeInterface { public function before(Context $ctx): void { error_log("Calling {$ctx->target} (request {$ctx->requestId})"); } public function after(Context $ctx): void { error_log("Finished {$ctx->target}"); } } // Register once at bootstrap (or worker startup) oxphp_register_decorator(LogDecorator::class);

oxphp_apm_trace()

php
oxphp_apm_trace(string $name, callable $callback, ?array $attributes = null): void

名前付きスパンの内部でコールバックを実行します。スパンはコールバックの実行前に開かれ、コールバックが戻った後に閉じられます。将来の拡張されたコールバック統合のために予約されています。

パラメーター:

  • $name — スパン名
  • $callback — スパン内部で実行するCallable
  • $attributes — 文字列のキーと値の属性からなる、オプションの連想配列

戻り値: void

oxphp_apm_start()

php
oxphp_apm_start(string $name, ?array $attributes = null): int

新しいスパンを開き、後で参照するためのローカルIDを返します。このスパンは、現在アクティブなスパン（アクティブなスパンがない場合はリクエストのルートスパン）の子になります。閉じるには oxphp_apm_end() を使用してください。

パラメーター:

  • $name — スパン名（例: "cache.warm"、"payment.process"）
  • $attributes — 作成時にスパンへ設定する、文字列のキーと値の属性からなるオプションの連想配列

戻り値: 整数のローカルスパンID。これを oxphp_apm_end()、oxphp_apm_attribute()、または $span_id を受け付ける他の関数に渡します。APMが無効化されている場合は 0 を返します。

例:

php
<?php $spanId = oxphp_apm_start('order.validate', [ 'order.type' => 'subscription', ]); validateOrder($order); oxphp_apm_end($spanId);

oxphp_apm_end()

php
oxphp_apm_end(int $span_id): void

oxphp_apm_start() で開いたスパンを閉じます。スパンの終了時刻が記録され、アクティブなスタックから完了リストへ移動して、エクスポートの準備が整います。

パラメーター:

  • $span_id — oxphp_apm_start() が返したローカルスパンID

戻り値: void

Note

スパンは常に逆順で閉じてください。スパンAを開いてからスパンBを開いた場合は、Aより先にBを閉じます。閉じられなかったスパンはリクエスト終了時に自動的に閉じられ、oxphp.span.leaked=true でマークされます。

oxphp_apm_attribute()

php
oxphp_apm_attribute(string $key, mixed $value, ?int $span_id = null): void

スパンにキーと値の属性を設定します。値は文字列に変換されます。$span_id が指定されない場合、属性は現在アクティブなスパンに追加されます。

パラメーター:

  • $key — 属性キー（例: "user.id"、"cache.hit"）
  • $value — 属性値（string、int、float、bool、またはnull — 文字列に変換されます）
  • $span_id — オプションのローカルスパンID。省略された場合、現在のスパンを対象とします

戻り値: void

例:

php
<?php $spanId = oxphp_apm_start('db.query'); oxphp_apm_attribute('db.system', 'mysql'); oxphp_apm_attribute('db.statement', 'SELECT * FROM users WHERE id = ?'); oxphp_apm_attribute('db.row_count', $rowCount, $spanId); oxphp_apm_end($spanId);

oxphp_apm_event()

php
oxphp_apm_event(string $name, ?array $attributes = null, ?int $span_id = null): void

スパンにタイムスタンプ付きのイベントを記録します。イベントは、スパンの存続期間内の個別の出来事（例: キャッシュミス、リトライの試行、認可チェック）をログに記録するのに便利です。

パラメーター:

  • $name — イベント名（例: "cache.miss"、"retry"）
  • $attributes — 文字列のキーと値のイベント属性からなる、オプションの連想配列
  • $span_id — オプションのローカルスパンID。省略された場合、現在のスパンを対象とします

戻り値: void

例:

php
<?php $spanId = oxphp_apm_start('payment.process'); oxphp_apm_event('payment.authorized', [ 'provider' => 'stripe', 'amount' => '49.99', ]); oxphp_apm_end($spanId);

oxphp_apm_error()

php
oxphp_apm_error(mixed $exception, ?int $span_id = null): void

スパンのステータスをエラー（ステータスコード2）としてマークします。例外や失敗が発生したスパンにフラグを立てるために使用します。

パラメーター:

  • $exception — 例外またはエラー（コンテキストとして使用されます。ステータスは型に関係なく設定されます）
  • $span_id — オプションのローカルスパンID。省略された場合、現在のスパンを対象とします

戻り値: void

例:

php
<?php $spanId = oxphp_apm_start('external.api'); try { $result = callExternalApi(); } catch (\Throwable $e) { oxphp_apm_error($e, $spanId); throw $e; } finally { oxphp_apm_end($spanId); }

oxphp_apm_status()

php
oxphp_apm_status(int $code, ?string $description = null, ?int $span_id = null): void

スパンにステータスコードとオプションの説明を設定します。

パラメーター:

  • $code — ステータスコード: 0 = Unset、1 = Ok、2 = Error
  • $description — オプションの人間が読める形式のステータス説明
  • $span_id — オプションのローカルスパンID。省略された場合、現在のスパンを対象とします

戻り値: void

例:

php
<?php $spanId = oxphp_apm_start('validation'); if ($valid) { oxphp_apm_status(1, 'Validation passed', $spanId); } else { oxphp_apm_status(2, 'Invalid input: missing email', $spanId); } oxphp_apm_end($spanId);

oxphp_apm_trace_id()

php
oxphp_apm_trace_id(): string

現在のリクエストのトレースコンテキストのW3CトレースID（16進数32文字）を返します。これは $_SERVER['OXPHP_TRACE_ID'] と同じ値で、スーパーグローバルなしで利用できます。

戻り値: 32文字の16進数のトレースID文字列。APMが無効化されている場合、またはアクティブなトレースコンテキストがない場合は、空の文字列を返します。

例:

php
<?php $traceId = oxphp_apm_trace_id(); error_log("Processing request in trace {$traceId}");

oxphp_apm_span_id()

php
oxphp_apm_span_id(): string

現在アクティブなスパンのスパンID（16進数16文字）を返します。ネストされたスパンがある場合は、最も内側の開いているスパンのIDを返します。

戻り値: 16文字の16進数のスパンID文字列。アクティブなスパンがない場合は、空の文字列を返します。

oxphp_apm_header()

php
oxphp_apm_header(): string

現在のスパンコンテキストに対するW3C traceparent ヘッダーの値を返します。これを使用して、下流のHTTP呼び出しにトレースコンテキストを伝播します。

戻り値: 00-{trace_id}-{span_id}-01 の形式の文字列。アクティブなトレースコンテキストがない場合は、空の文字列を返します。

例:

php
<?php $spanId = oxphp_apm_start('http.call'); $traceparent = oxphp_apm_header(); $response = file_get_contents('https://api.example.com/data', false, stream_context_create([ 'http' => [ 'header' => "traceparent: {$traceparent}\r\n", ], ]) ); oxphp_apm_end($spanId);

OxPHP\Profile\is_active()

php
OxPHP\Profile\is_active(): bool

このリクエストに対してプロファイルのキャプチャが現在アクティブなとき、つまりプロファイラーがトリガーされ（ヘッダー、クッキー、クエリパラメーター、またはサンプルレートによって）、キャプチャが pause() で一時停止されていないときに true を返します。

プロファイリングがオンのときにのみ実行すべき、コストの高い計測をガードするのに便利です。

戻り値: bool。

例:

php
<?php if (OxPHP\Profile\is_active()) { OxPHP\Profile\mark('checkpoint.before_query'); }

OxPHP\Profile\start()

php
OxPHP\Profile\start(): void

RINITでトリガーが発火しなかった場合でも、現在のリクエストの残りの部分に対してプログラム的にプロファイルのキャプチャを有効にします。プロファイリングモードを PROFILE_ALL に設定し、一時停止フラグをクリアします。

プロファイルが既に別のモードでアクティブだった場合、この呼び出しはそれを昇格させます。より低いモードで既に収集されていたスパンは、キャプチャされたプロファイルが内部的に一貫性を保つように破棄されます。トリガーに頼らずに特定のコードパスをプロファイリングの対象にしたい場合に使用してください。

戻り値: void。

例:

php
<?php if ($request->header('x-debug') === 'on') { OxPHP\Profile\start(); }

OxPHP\Profile\stop()

php
OxPHP\Profile\stop(): void

このリクエストに対する以降のスパンキャプチャを無効にします。現在開いているスパンは、PHPがそれらから戻る際に自然に閉じられるため、呼び出しスタックはバランスが保たれます。新しいスパンの記録が停止するだけです。

戻り値: void。

例:

php
<?php OxPHP\Profile\start(); expensive_work(); OxPHP\Profile\stop(); non_profiled_work();

OxPHP\Profile\pause()

php
OxPHP\Profile\pause(): void

stop() のソフト版です。効果は同じ（一時停止フラグを設定します）で、違いは意図にあります。pause() はキャプチャが後で resume() を介して再開されることを示すのに対し、stop() はそうではありません。

戻り値: void。

OxPHP\Profile\resume()

php
OxPHP\Profile\resume(): void

pause() または stop() が設定した一時停止フラグをクリアします。プロファイルモード自体は変更されません。一度も有効になっていなかった場合、resume() は観測可能な動作を何も行いません。

戻り値: void。

例:

php
<?php OxPHP\Profile\pause(); $secret = decrypt_payload($data); OxPHP\Profile\resume();

OxPHP\Profile\mark()

php
OxPHP\Profile\mark(string $label, ?array $attrs = null): void

最上位の開いているスパンに Mark イベントを、オプションの属性バッグとともに付加します。開いているスパンがない場合（例: プロファイリングが非アクティブ、または計測されたフレームの外側でリクエストのトップレベルから mark() が呼び出された場合）はno-opになります。

属性のキーと値は文字列に強制変換されます。文字列でない値は空の文字列になります。

パラメーター:

  • $label — イベントの短い人間が読める形式の名前（例: "cache.miss"、"db.slow_query"）
  • $attrs — イベントに付加される、オプションの array<string, scalar> のキー／値ペア

戻り値: void。

例:

php
<?php function load_user(int $id): array { $cached = $cache->get("user:$id"); if ($cached === null) { OxPHP\Profile\mark('cache.miss', ['key' => "user:$id"]); $cached = $db->fetchUser($id); } return $cached; }

OxPHP\Profile\metric()

php
OxPHP\Profile\metric(string $name, float $value): void

現在の開いているスパンに metric.<name> 属性を追加します。開いているスパンがない場合はno-opになります。

mark()（個別のイベントを作成する）とは異なり、metric() は既存のスパンの属性セットに書き込みます。周囲の操作に紐づいた数値的な観測（取得した行数、処理したバイト数、リトライ回数）を記録するのに便利です。

パラメーター:

  • $name — メトリクス識別子。metric.<name> として格納されます
  • $value — 数値（float に強制変換されます）

戻り値: void。

例:

php
<?php function search(string $query): array { $results = $index->search($query); OxPHP\Profile\metric('result_count', count($results)); return $results; }

クラスとインターフェース

oxphp_sapi 拡張は以下のクラスを登録します。

HTTP

クラス 説明
OxPHP\Http\Request oxphp_http_request() が返すリクエストオブジェクト。final — 継承できません。
OxPHP\Http\Attributes 変更可能なリクエスト属性コンテナ（ミドルウェア用）。final。
OxPHP\Http\Session $request->session() を介してアクセスできるセッションオブジェクト。final。
OxPHP\Http\UploadedFile $request->files() から得られるアップロードファイルオブジェクト。final。

デコレーター

クラス／インターフェース 説明
OxPHP\Decorator\AttributeInterface デコレーター用のインターフェース。before(Context $ctx) および after(Context $ctx) メソッドを必要とします。
OxPHP\Decorator\Context デコレーターのフックに渡されるコンテキストオブジェクト。final。パブリックプロパティ: target、class、method、function、objectId、requestId、traceId。メソッド: getParams(): array、getResult(): mixed、hasResult(): bool。完全なリファレンスは Decorators を参照してください。

トレーシング

クラス 説明
OxPHP\Apm\Trace 自動的なスパン作成のための組み込みアトリビュート。関数またはメソッドに適用します。

Async

クラス 説明
OxPHP\Async\BorrowedProxy スレッド間で借用される値のためのプロキシオブジェクト。

例外

拡張が登録するすべての例外:

例外 継承元 スローされるとき
OxPHP\Async\AsyncException \Exception 非同期タスク内のエラー（oxphp_async_await()）、または oxphp_async() での無効な引数
OxPHP\Async\TimeoutException OxPHP\Async\AsyncException oxphp_async_await()、oxphp_async_await_all()、oxphp_async_await_race()、oxphp_async_await_any() のいずれかでタイムアウトを超過。oxphp_async_await_any() のタイムアウトの場合は、アクセサー getPartialErrors(): array<int, \Throwable> および getCancelledPromiseIds(): list<int> が値を持ちます。他の呼び出し元では両方とも [] を返します。
OxPHP\Async\AggregateAsyncException OxPHP\Async\AsyncException すべてのPromiseがrejectされたときに oxphp_async_await_any() によってスローされます。メソッド: getErrors(): list<\Throwable>（位置ベース、入力位置により0..N-1のキー）、getErrorMap(): array<int, \Throwable>（promise idをキーとする）、getPromiseIds(): list<int>（入力のpromise idを順序どおり）。
OxPHP\Async\BorrowException \Exception スレッド間で値を借用する際のエラー
OxPHP\Http\Exception\NoActiveRequestException \RuntimeException アクティブなリクエストの外部で oxphp_http_request() を呼び出した場合
OxPHP\Http\Exception\AsyncContextException NoActiveRequestException oxphp_async() のコールバック内で oxphp_http_request() を呼び出した場合
OxPHP\Http\Exception\WorkerIdleException NoActiveRequestException ワーカーモードでリクエストとリクエストの間に oxphp_http_request() を呼び出した場合
OxPHP\Decorator\RejectedException \Exception デコレーターが関数／メソッド呼び出しを拒否した場合

拡張の検証

OxPHP拡張がロードされていることを検証し、登録されたすべての関数を確認できます。

php
<?php if (extension_loaded('oxphp_sapi')) { echo "OxPHP extension is loaded\n"; } $functions = get_extension_funcs('oxphp_sapi'); print_r($functions); // Array // ( // [0] => oxphp_http_request // [1] => oxphp_superglobals_enabled // [2] => oxphp_request_id // [3] => oxphp_worker_id // [4] => oxphp_server_info // [5] => oxphp_finish_request // [6] => oxphp_is_worker // [7] => oxphp_is_streaming // [8] => oxphp_stream_flush // [9] => oxphp_sleep // [10] => oxphp_usleep // [11] => oxphp_worker // [12] => oxphp_register_decorator // [13] => oxphp_async // [14] => oxphp_async_await // [15] => oxphp_async_await_all // [16] => oxphp_async_await_race // [17] => oxphp_async_await_any // [18] => oxphp_apm_trace // [19] => oxphp_apm_start // [20] => oxphp_apm_end // [21] => oxphp_apm_attribute // [22] => oxphp_apm_event // [23] => oxphp_apm_error // [24] => oxphp_apm_status // [25] => oxphp_apm_trace_id // [26] => oxphp_apm_span_id // [27] => oxphp_apm_header // )
Note

コアのSAPI関数（oxphp_register_decorator まで）が最初に来ます。oxphp_async_* および oxphp_apm_* ファミリー — そしてプロファイラーが組み込まれている場合の OxPHP\Profile\* SDK — は、モジュール初期化時に各プラグインによって追加されます。このリストは説明用として扱ってください。正確なセットと順序は、どのプラグインがビルドにコンパイルされているかによって異なります。

PHP-FPMとの互換性

コードがOxPHPとPHP-FPMの両方で動作しなければならない場合は、フォールバックラッパーを使用してください。

php
<?php function finish_request(): bool { if (function_exists('oxphp_finish_request')) { return oxphp_finish_request(); } if (function_exists('fastcgi_finish_request')) { return fastcgi_finish_request(); } return false; } // Worker-aware bootstrap if (function_exists('oxphp_is_worker') && oxphp_is_worker()) { // OxPHP worker mode } else { // PHP-FPM or OxPHP traditional mode }
Note

oxphp_async() ファミリーの関数はOxPHPで常に登録されるため、ASYNC_WORKERS=0 の場合でも function_exists('oxphp_async') は true を返します。プールが無効化されている場合、いずれかの非同期関数を呼び出すと OxPHP\Async\AsyncException がスローされます。コードが両方の構成を処理しなければならない場合は、function_exists() をチェックするのではなく例外をキャッチしてください。

関連項目

  • HTTP Request API — oxphp_http_request() を介したリクエストデータへのオブジェクト指向アクセス
  • Worker Mode — 永続的なワーカーループとリクエストライフサイクル
  • Server-Sent Events — oxphp_stream_flush() によるリアルタイムストリーミング
  • Early Response — oxphp_finish_request() によるバックグラウンド処理
  • Superglobals — OxPHPが $_SERVER、$_GET、$_POST、およびその他のスーパーグローバルをどのように生成するか
  • Distributed Tracing & APM — W3C Trace Context、OTelエクスポート、および oxphp_apm_*() SDK
  • Configuration Reference — WORKER_MODE_ENABLED、ENTRY_FILE、PHP_WORKERS、およびその他の環境変数
code
間違いを見つけましたか？報告する →