【実務・中級編】PHPにおける`WeakMap`の内部実装と参照カウント・GCとの連携 – PHPコア・内部エンジンと高速化・並行処理の極意解析バイブル

はじめに：なぜコードレビューで `WeakMap` が急浮上するのか

テックリードとしてコードレビューを行っていると、キャッシュ機構やORMの内部状態管理、あるいはリクエストスコープのDIコンテナにおいて、不気味なメモリリークに遭遇することがある。
「すべてのオブジェクトを配列に保存し、処理が終わったら `unset()` しているはずなのに、なぜかRSS（Resident Set Size）が肥大化し続ける」——この恐怖の根源の大半は、PHPの強参照（Strong Reference）と循環参照、そしてZendエンジンが誇る参照カウント機構の罠にある。

PHP 8.0で導入された `WeakMap` は、このメモリ管理のパラダイムを根本から変える強力な武器だ。しかし、その内部実装（Zend VMレベルでのオブジェクトとバケットの結びつき）を理解せずに使えば、単なる「バグの隠し場所」になり下がる。

本稿では、`WeakMap` がどのようにオブジェクトへの弱い参照を保持し、いかにしてGC（ガベージコレクション）のサイクルから解放されているのか、その低レイヤの真実を解き明かす。

—

1. 内部メカニズム：Zendエンジンから見た `WeakMap` の正体

参照カウント（Reference Counting）の限界

PHPの変数はすべて `zval` という構造体で表現される。オブジェクト型（IS_OBJECT）の `zval` は、実体である `zend_object` へのポインタを保持しており、そこには `gc_refcount`（参照カウント）という整数値が存在する。
通常の配列やSplObjectStorageにオブジェクトを格納すると、その `gc_refcount` はインクリメントされる。つまり、開発者が「もう不要だ」と思って変数への参照を断っても、コレクションの中に格納されている限り、参照カウントは `0` にならず、メモリ空間（Zendメモリマネージャ: emalloc/efree）から解放されない。

`WeakMap` が行う「弱い参照」の魔法

`WeakMap` は、キーにオブジェクト、値に任意の型（スカラー値やオブジェクト）を持つマップ構造だが、キーであるオブジェクトの `gc_refcount` を一切増加させない。

Zendエンジンの内部において、`WeakMap` は保持しているキー（オブジェクト）のリストやハッシュテーブルのバケット側から、対象の `zend_object` に対する「オブザーバー（監視者）」としての弱参照リスト（`zend_weakref`）を構築している。
オブジェクトが破棄される瞬間、Zendエンジンはライフサイクル管理の一環として、そのオブジェクトを監視しているすべての `WeakMap` インスタンスに対し、該当エントリの即時削除を通知する。これにより、メモリリークの温床となる「ゾンビエントリ」が物理的に存在できなくなる仕組みだ。

—

2. 循環参照GCとの協調動作

PHPの循環参照GC（Concurrent Garbage Collector）は、参照カウントが `0` にならなくなった「循環参照の疑いがあるバッファ」を定期的にスキャンし、一網打尽に回収する。

ここで重要なのは、`WeakMap` のキーは循環参照の検出対象外（あるいは影響を与えない）という点だ。
もし `WeakMap` が強参照を持っていた場合、「オブジェクトAがWeakMapを保持し、WeakMapのキーがオブジェクトAを指す」といった複雑なグラフ構造が生まれた瞬間にGCのバッファが汚れ、回収効率が著しく低下する。`WeakMap` はこのエコシステムを汚染せず、オブジェクトのライフサイクルに完全にスレーブ（従属）として寄り添う。

—

3. 実務で直面する課題：リクエストスコープキャッシュの堅牢な設計

ここからは、実務の現場で即座に使える設計パターンを見ていこう。
Webアプリケーション（特に長寿命なWorkerプロセスを使用する FrankenPHP や RoadRunner、あるいは Swoole）において、各サービスやエンティティに紐づく「リクエスト固有のメタデータや計算結果」を安全にキャッシュするアーキテクチャは極めて重要である。

以下のコードは、オブジェクトのライフサイクルに完全に同期し、明示的なクリーンアップを不要にするリクエストスコープキャッシュの堅牢な実装例である。

declare(strict_types=1);

namespace App\Infrastructure\Cache;

use WeakMap;
use LogicException;

Class EntityMetadataCache
ドメインモデル（エンティティ）のライフサイクルに完全に依存した
メモリリークフリーのメタデータキャッシュコンテナ。
FrankenPHPやRoadRunnerなどの永続プロセス環境においても安全に動作する。

/
final class EntityMetadataCache
{
/

@var WeakMap>
オブジェクトをキーに持つため、オブジェクトが破棄された瞬間に
エントリは自動的に消去され、メモリリークを根絶する。

/
private WeakMap $cache;

public function __construct()
{
/ @var WeakMap> /
$this->cache = new WeakMap();
}

キャッシュからデータを取得、存在しない場合はコールバックを実行して格納する

@template T of object
@param T $entity
@param string $key
@param callable(T): mixed $resolver
@return mixed

/
public function remember(object $entity, string $key, callable $resolver): mixed
{
// WeakMapのオフセットアクセスは内部でzend_objectポインタをハッシュ化する
if (!isset($this->cache[$entity])) {
$this->cache[$entity] = [];
}

if (!array_key_exists($key, $this->cache[$entity])) {
// ログやデバッグ用のコンテキストを出力（開発環境想定）
// error_log(sprintf(‘Cache miss for entity [%s], key [%s]’, get_class($entity), $key));

$this->cache[$entity][$key] = $resolver($entity);
}

return $this->cache[$entity][$key];
}

特定のエンティティのキャッシュを明示的に無効化する
（オブジェクトの破棄を待たずに即時解放したい場合）

/
public function invalidate(object $entity): void
{
if (isset($this->cache[$entity])) {
unset($this->cache[$entity]);
}
}

現在マップが保持しているアクティブなエントリ数を取得する
（デバッグやモニタリング用）

/
public function countActiveEntities(): int
{
// WeakMapは Countable インターフェースを実装している
return count($this->cache);
}
}

この設計が実務で優れている理由

1. プロセス環境への耐性: 従来の静的プロパティ（`public static array $cache`）を使ったキャッシュは、長期稼働するプロセスにおいてメモリ爆発を引き起こすが、この `EntityMetadataCache` ならば、対象のエンティティがコントローラやサービス層のスコープを抜けて破棄された瞬間、メモリは即座に解放される。
2. 型安全とスケーラビリティ: PHP 8のプロパティ型宣言により、`WeakMap` であることが保証されており、予期せぬスカラー値の混入を防ぐ。

—

4. チーフアーキテクトからの警鐘：陥りがちなアンチパターン

最後に、コードレビューでしばしば見かける「危険な使い方」を指摘しておく。

アンチパターン1: 値（バリュー）側にオブジェクトを格納して満足する

`WeakMap` が「弱い参照」を張るのはキー（Key）に対してのみである。
値（Value）側に別のオブジェクトを格納した場合、その値側のオブジェクトは強参照されるため、キーが消えても値側のオブジェクトが別の場所から参照されていればメモリに残る。
「マップ全体のメモリを自動で消したいから」といって、依存関係の方向を誤ると、意図しないメモリリークの温床となる。

アンチパターン2: スカラー値をキーにしようとする

`WeakMap` のキーにはオブジェクトしか指定できない。無理に `spl_object_id()` や文字列をキーにしようとすると `TypeError` が発生する。
もしスカラー値とオブジェクトの寿命を同期させたい場合は、オブジェクトをキーにし、スカラー値を値側に配置するというメンタルモデルの反転が必要となる。

—

おわりに

PHPは、単なる「動的なスクリプト言語」という初期のレッテルを完全に脱ぎ捨て、Zendエンジンの最適化とともに、極めて堅牢でモダンなエンタープライズ言語へと進化を遂げた。
その中で `WeakMap` は、低レイヤのメモリ管理とオブジェクトのライフサイクルをエンジニアが手元でコントロールするための、最高峰の道具の一つである。

「なぜこのメモリは解放されないのか」と夜中に頭を抱える前に、Zendエンジンの参照カウントの仕組みに思いを馳せ、適切な箇所に `WeakMap` を配置する。その洗練された設計こそが、一流のPHPアーキテクトの証である。