【実務・中級編】Fiberとコンテキストローカルストレージ（CLS）の実現方法：Fiber固有データの管理 – PHPコア・内部エンジンと高速化・並行処理の極意解析バイブル

Fiberとコンテキストローカルストレージ（CLS）の極意：Zend VMのスタック退避と並行処理の罠

PHP 8.1でのFiber（ファイバー）の導入は、PHPにおける非同期並行処理のパラダイムを根本から変えた。しかし、Node.jsの`AsyncLocalStorage`やJavaの`ThreadLocal`に慣れ親しんだエンジニアが、その感覚のままFiberを扱って痛い目を見るケースが後を絶たない。

結論から言おう。PHPのFiberは「プリエンプティブ（強制割り込み型）」ではなく「コオペラティブ（協調型）」であり、Zend VMの実行コンテキストをユーザーランドで手動スイッチする仕組みに過ぎない。この特性を理解せずにグローバルな状態管理を行うと、マルチテナント環境や高負荷なAPIサーバーにおいて、「他人のリクエストコンテキストが別のFiberに漏洩する」という致命的なセキュリティホールや、メモリリークを引き起こす。

今回は、PHPの内部エンジン（Zend VM）の挙動を踏まえ、Fiber環境下で安全かつ堅牢な「コンテキストローカルストレージ（CLS）」を如何にして構築するか、その設計思想と実装の全貌を解説する。

—

1. なぜ従来の静的プロパティやグローバル変数が破綻するのか

PHPの伝統的なWebアプリケーション（FPMモデル）では、1リクエスト＝1プロセス（またはスレッド）という強力なアイソレーション（隔離）があった。そのため、以下のようなコードは一般的に「動く」ように見えた。

class RequestContext {
private static ?array $data = null;

public static function set(string $key, mixed $value): void {
self::$data[$key] = $value;
}

public static function get(string $key): mixed {
return self::$data[$key] ?? null;
}
}

しかし、イベントループ（ReactPHPやAmpなど）上でFiberを駆使し、1つのプロセス内で数千の並行リクエストをさばく非同期アーキテクチャに移行した瞬間、この設計は完全に崩壊する。

Zend VMの視点から見ると、Fiberがサスペンド（一時停止）し、別のFiberへ実行権が移譲（`Fiber::suspend()` / `Fiber::resume()`）されたとき、静的プロパティ（`self::$data`）はプロセス全体で共有されるグローバル領域に居座り続ける。
つまり、Fiber Aが処理している途中でFiber Bにコンテキストが切り替わり、Fiber Bが`RequestContext`を書き換えた場合、再びFiber Aに戻ったときにはデータが書き換わっている、あるいは消失しているという「状態の汚染（State Pollution）」が発生するのだ。

—

2. Fiber固有データを安全に管理するCLS（Context Local Storage）の設計

では、Fiberごとに独立したスコープを持つストレージをPHPでどう実現すべきか。
答えはシンプルだ。「現在実行中のFiberインスタンス自体をキー（または識別子）として、ストレージのHashTableをカプセル化する」ことである。

PHPの`Fiber::getCurrent()`を使えば、今まさにZend VMが実行しているFiberオブジェクトのインスタンスを取得できる。これを利用して、オブジェクトのライフサイクルに紐づいたコンテキストマネージャを構築する。

以下に、実務のプロダクション環境（イベント駆動型APIサーバー等）に耐えうる、堅牢なCLSの実装コードを示す。

実用リファレンスコード：`FiberContext`

declare(strict_types=1);

namespace App\Concurrency;

use Fiber;
use WeakMap;
use LogicException;

Fiberコンテキストローカルストレージ（CLS）マネージャ
Zend VMのFiberインスタンスをキーにして、コンテキストデータを安全に隔離・管理する。

/
final class FiberContext
{
/

ガベージコレクションを阻害しないためのWeakMap
Fiberが破棄されたら自動的にエントリも解放され、メモリリークを防ぐ。
@var WeakMap>

/
private static WeakMap $storage;

private static function init(): void
{
if (!isset(self::$storage)) {
self::$storage = new WeakMap();
}
}

現在のFiberコンテキストに値路をセットする

/
public static function set(string $key, mixed $value): void
{
self::init();
$fiber = Fiber::getCurrent();

if ($fiber === null) {
// Fiberの外（メインスレッド・グローバルコンテキスト）で呼ばれた場合のフォールバック、
// もしくは厳格に例外を投げる設計にする。ここではグローバル配列として扱う簡易実装。
throw new LogicException(‘FiberContext must be accessed within an active Fiber.’);
}

// WeakMapから現在のFiberに対応するストレージ配列を取得、なければ初期化
if (!isset(self::$storage[$fiber])) {
self::$storage[$fiber] = [];
}

self::$storage[$fiber][$key] = $value;
}

現在のFiberコンテキストから値を取得する

/
public static function get(string $key, mixed $default = null): mixed
{
self::init();
$fiber = Fiber::getCurrent();

if ($fiber === null) {
return $default;
}

return self::$storage[$fiber][$key] ?? $default;
}

現在のFiberコンテキストを完全にクリーンアップする（メモリ最適化）

/
public static function destroy(): void
{
self::init();
$fiber = Fiber::getCurrent();

if ($fiber !== null && isset(self::$storage[$fiber])) {
unset(self::$storage[$fiber]);
}
}
}

—

3. この設計が「プロのコード」である理由（内部構造の解説）

上記のコードが優れている理由は、単に動くということだけではない。PHPの低レイヤのメモリ管理メカニズムとガベージコレクション（GC）の仕様を熟知した上で、落とし穴を完全に塞いでいるからだ。

① `WeakMap` によるメモリリークの完全防止

通常、PHPでオブジェクトをキーにしたマップを作ろうとすると、そのオブジェクトへの強い参照（Strong Reference）が残り続け、処理が終わってもメモリから解放されない（メモリリークの温床になる）。
しかし、PHP 8.0で導入された `WeakMap` を使用することで、Fiberオブジェクトがライフサイクルを終えて破棄された瞬間、ZendエンジンのGCによってマップ内のデータも自動的にパージされる。長期間稼働するデーモンプロセス（SwooleやReactPHPベースのアプリケーション）において、この配慮がないコードは数時間でメモリを枯渇させる。

② 明示的なスコープ分離

`Fiber::getCurrent()` が `null` を返すメインフローと、Fiber内の非同期処理を明確に分離している。これにより、従来の同期コードと非同期コードが混在するレガシーなコードベースであっても、どこでコンテキストが汚染されているかを早期に検知（例外スロー）できる。

—

4. 実務での活用パターン：トランザクションとリクエストトレーシング

このCLS（`FiberContext`）は、具体的にどのような場面で真価を発揮するのか。最も一般的なユースケースが「リクエストトレーシング（相関IDの伝播）」と「データベーストランザクションの伝播」である。

以下は、非同期HTTPハンドラ内で、各Fiberが独立した相関ID（Correlation ID）を保持し、ログ出力時に自動付与する実践的なコード例だ。

use App\Concurrency\FiberContext;
use Fiber;

// 擬似的なイベントループ・リクエストハンドラ
function handleAsyncRequest(string $requestId, string $payload): Fiber
{
return new Fiber(function () use ($requestId, $payload) {
// 1. Fiberのライフサイクル開始時にCLSへコンテキストを格納
FiberContext::set(‘correlation_id’, $requestId);
FiberContext::set(‘auth_user_id’, ‘user_998877’);

echo “[Fiber START] Handled by ” . (Fiber::getCurrent() ? ‘Fiber’ : ‘Main’) . “\n”;

// 非同期処理をシミュレート（I/O待ちでサスペンド）
processWithIoWait($payload);

// 2. どこからでも安全にCLS経由でコンテキストを引き出せる
$currentId = FiberContext::get(‘correlation_id’);
echo “[Log] Processing completed for Correlation ID: {$currentId}\n”;

// 3. 処理終了時は確実に破棄（またはWeakMapの自動解放に委ねる）
FiberContext::destroy();
});
}

function processWithIoWait(string $data): void
{
// 内部でFiberがサスペンドするような処理（DBクエリや外部APIコール）を想定
// ここで他のFiberにコンテキストが切り替わっても、FiberContext::get()の値は絶対に混ざらない。
Fiber::suspend();
}

// — 実行シミュレーション —
$fiberA = handleAsyncRequest(‘req-uuid-001’, ‘Payload A’);
$fiberB = handleAsyncRequest(‘req-uuid-002’, ‘Payload B’);

// 並行実行のシミュレーション
$fiberA->start(); // req-uuid-001 のコンテキストがセットされてサスペンド
$fiberB->start(); // req-uuid-002 のコンテキストがセットされてサスペンド

$fiberA->resume(); // 再びfiberAに戻る。CLSにより correlation_id は ‘req-uuid-001’ が厳格に維持されている。
$fiberB->resume(); // fiberBを再開。

—

5. テクニカルリードからの総括・警告

PHPにおけるFiberは非常に強力な武器であるが、それは「諸刃の剣」でもある。同期処理の頭のままグローバル変数や静的プロパティに依存した設計を続けると、並行処理環境下において「再現極めて困難なバグ（Race Condition）」の温床となる。

アーキテクトやシニアエンジニアとしてコードレビューを行う際は、以下のポイントを徹底的にチェックしてほしい。

1. Fiber内でグローバル変数、静的プロパティ、シングルトンインスタンスに「可変な状態（State）」を保持していないか？
2. 非同期I/Oを挟む処理において、リクエスト固有の情報が別のFiberにリークする余地がないか？
3. 長期稼働プロセスにおいて、メモリリーク対策（`WeakMap`の活用や明示的なクリーンアップ）が担保されているか？

これらをクリアした堅牢なコンテキスト管理こそが、モダンでハイパフォーマンスなPHPアプリケーションを支える基盤となる。型とメモリ構造を支配する者だけが、PHPの真のパフォーマンスを引き出すことができるのだ。