【実務・中級編】OPcacheプリローディングの物理構造と共有メモリ（SHM）への配置戦略：デプロイメント時のパフォーマンス最適化 – PHPコア・内部エンジンと高速化・並行処理の極意解析バイブル

2026.08.31

OPcacheプリローディングの物理構造と共有メモリ（SHM）戦略：Zend VMの深淵を支配する者へ

テックリードの私から、コードレビューでよく見かける「なんとなく動く」プリローディング設定に終止符を打つための知見を授けよう。

PHP 7.4で導入され、8.x代で成熟を極めたOPcacheプリローディング（Preloading）。これを単なる「ファイル読み込みの高速化機能」だと思っているなら、Zend Engineのメモリモデルを根本から誤解している。プリローディングの本質は、「リクエスト毎に行われていたクラスのシンボル解決とAST（抽象構文木）からオペコードへのコンパイルを、親プロセス（PHP-FPM Master）の起動時に一発で行い、全子プロセス間で共有メモリ（SHM）として永続化する仕組み」である。

今回は、このプリローディングが共有メモリ上でどのような物理構造を形成し、デプロイメント時にいかにして致命的なメモリリークや「ゴーストクラス問題」を防ぐのか、その極意を低レイヤの視点から紐解く。

—

1. 共有メモリ（SHM）におけるクラス定義の物理構造

通常、PHPのライフサイクルでは、リクエストが来ると毎回 `zend_ini` やファイルシステムへのアクセスが発生し、`zend_compile_file` が走ってスクリプトがコンパイルされる。生成されたオペコード（`zend_op_array`）やクラスエントリ（`zend_class_entry`）は、リクエストの終了とともに破棄されるプロセスローカルなメモリ（EMALLOC / PMALLOC）上に構築される。

しかし、`opcache.preload` を有効にしてサーバーを起動すると、何が起きるか。

Zend Engineは、指定されたスクリプトをマスタープロセス上で実行し、そこで定義されたすべての関数、クラス、トレイト、インターフェースを、OPcacheの共有メモリ（SHM）セグメント内へと完全にコピー（またはインプレースで昇格）させる。

[ PHP-FPM Master Process ]
└─ 起動時にプリロードスクリプトを実行
└─ クラス定義・オペコードを生成
│
▼ (SHMへの書き込み & 永続化)
[ Shared Memory (SHM) / OPcache Segment ]
├─ zend_class_entry (User Class A) ── 指針・メソッドポインタ
├─ zend_class_entry (User Class B)
└─ zend_op_array (Optimized Opcodes)
▲
│ (読み取り専用・コピーレスで共有)
[ PHP-FPM Worker Process 1, 2, 3… ]
└─ リクエスト処理時にSHM上のポインタを直接参照

ここで重要なのは、ワーカープロセスはこの共有メモリ上のクラス定義を「読み取り専用（Copy-on-Writeの変形）」として共有する点だ。各子プロセスは独自のメモリ領域にクラス構造体を持つ必要がなくなり、プロセス起動時のオーバーヘッドが極限まで削ぎ落とされる。

だが、この「永続化」という特性こそが、デプロイメント時における最大の罠となる。

—

2. デプロイメントの悪夢：「ゴーストクラス」とメモリリークのメカニズム

コードレビューで「とりあえずフレームワークのコアファイルを全部preloadしましょう」と提案するジュニアがいたら、即座に差し戻さなければならない。なぜか。

罠①：デプロイ時のコード不整合（ゴーストクラス）

OPcacheのSHMに一度ロードされたクラスは、PHP-FPMのマスタープロセスが再起動されない限り、物理ファイルが書き換わっても絶対に更新されない。
もしデプロイ時にファイルを差し替えても、FPMのワーカーが古いSHM上のクラス定義を参照し続けるか、あるいは依存関係の解決順序（Circular Dependency）を誤ると、メモリ上の古いクラス構造と新しいコードの間で不整合が生じ、`Fatal Error: Declaration of X must be compatible with Y` といった不可解なエラーが本番環境を直撃する。

罠②：SHMの断片化とメモリリーク

プリロードされたクラスが持つ静的プロパティ（`public static $cache = []` など）は、SHM上の初期化された状態で固定化される。ここにリクエストごとに動的なデータを蓄積するような設計にしていると、共有メモリ領域が汚染され、最悪の場合はOOM（Out of Memory）を引き起こす。

—

3. 実務で破綻しない、堅牢なプリロード構築戦略

これらの課題をクリアし、真にパフォーマンスを最大化するための実務用プリロードスクリプトの設計パターンを提示する。

以下のスクリプトは、単にファイルを読み込むだけでなく、ディレクトリ構造の再帰的走査、例外処理、そしてメモリ効率を考慮した安全なインクルードを担保するプロダクションクオリティのコードである。

  • 堅牢なOPcacheプリローディング制御クラス
  • [設計思想]
  • – 依存関係の順序を考慮したファイル走査
  • – 存在しないファイルや構文エラーに対するフェイルセーフ
  • – 開発環境と本番環境の厳密な環境分離

    • /
    final class PreloadManager
    {
    private string $baseDir;
    / @var string[] 除外するディレクトリ・パターンのリスト /
    private array $excludePatterns;

    public function __construct(string $baseDir, array $excludePatterns = [])
    {
    get_required_env(); // 本番環境チェックの擬似関数
    $this->baseDir = rtrim($baseDir, ‘/’);
    $this->excludePatterns = $excludePatterns;
    }

    public function execute(): void
    {
    $startTime = microtime(true);
    $loadedCount = 0;

    $iterator = new \RecursiveIteratorIterator(
    new \RecursiveDirectoryIterator($this->baseDir, \FilesystemIterator::SKIP_DOTS)
    );

    / @var \SplFileInfo $file /
    foreach ($iterator as $file) {
    if ($file->getExtension() !== ‘php’) {
    continue;
    }

    $filePath = $file->getRealPath();

    if ($this->shouldExclude($filePath)) {
    continue;
    }

    try {
    // zend_execute_scriptsではなくopcodeキャッシュに乗せるためのinclude
    // プリロード時は実行結果（戻り値）は捨てられ、シンボルテーブルへの登録のみが目的となる
    opcache_compile_file($filePath);
    $loadedCount++;
    } catch (\Throwable $e) {
    // プリロード中の致命的なエラーはマスターの起動を止めるため、
    // ログに吐き出して握りつぶすか、安全に例外を伝播させる
    error_log(sprintf(
    ‘[Preload Error] Failed to compile: %s. Reason: %s’,
    $filePath,
    $e->getMessage()
    ));
    }
    }

    $duration = microtime(true) – $startTime;
    error_log(sprintf(‘[Preload Success] Compiled %d files in %.4f seconds.’, $loadedCount, $duration));
    }

    private function shouldExclude(string $filePath): bool
    {
    foreach ($this->excludePatterns as $pattern) {
    if (preg_match($pattern, $filePath)) {
    return true;
    }
    }
    return false;
    }
    }

    // — 実行エントリポイント (preload.phpとして配置) —
    // CLI環境かつFPMマスターのコンテキストでのみ実行を許可
    if (PHP_SAPI !== ‘cli’ && php_sapi_name() !== ‘fpm-fcgi’) {
    // 厳密にはopcache.preloadはCLI経由のマスター起動時に読まれる
    }

    $appRoot = ‘/var/www/html/app’;
    $exclusions = [
    ‘#/(Tests|Migrations|Config)/#’, // テストコードやマイグレーションはプリロード不要
    ‘#app/Cache/#’,
    ];

    (new PreloadManager($appRoot, $exclusions))->execute();

    —

    4. デプロイメントパイプラインの組立て方：ゼロダウンタイムとFPMリロード

    プリロードを導入したシステムでは、デプロイ手順が変わる。単にファイルを同期するだけでは古いクラスがメモリに残るため、必ず以下のフローをCI/CDパイプラインに組み込む必要がある。

    1. 新コードの同期（Atomic Deploy）
    2. OPcacheキャッシュのクリア（必要に応じて `opcache_reset()` を実行するか、新プロセスで上書き）
    3. PHP-FPMのグレースフルリロード（Graceful Reload）

    特に重要なのはステップ3だ。PHP-FPMのマスタープロセス（およびプリロードスクリプト）は、FPMの「リロード（`systemctl reload php-fpm`）」が行われたタイミングで初めて再評価される。ワーカープロセスの再起動（`restart`）だけではマスターのメモリ空間はリロードされないケースがあるため、インフラ層での正しいシグナル制御（`SIGUSR2` によるマスタープロセスの再起動）が不可欠となる。

    —

    5. リードアーキテクトからの最終提言

    OPcacheプリローディングは、適切に扱えばフレームワークのブートストラップコストをほぼゼロにし、スループットを劇的に向上させる強力な武器だ。しかし、その裏で「メモリ上の静的状態とファイル上の動的コードの乖離」という、デバッグが極めて困難な矛盾を生み出すリスクを常に孕んでいる。

    コードレビューにおいては、以下の3点を徹底的にチェックせよ。

    • 「本当にプリロードが必要なクラスか？」（頻繁に変更が入るドメインモデルやアプリケーション層のビジネスロジックをpreloadしていないか。フレームワークのコアやライブラリに限定されているか）
    • 「静的プロパティの汚染対策がなされているか」
    • 「CI/CDでFPMマスターの再起動が確実に行われるフローになっているか」

    これらをクリアしたとき、あなたのWebシステムは、Zend VMの限界を引き出した最高峰のパフォーマンスを発揮するだろう。

    スポンサーリンク
    " "
    タイトルとURLをコピーしました