Reduce static memory retention of decoded OpenAPI specs during test runs

[wadakatu]

Problem

大規模テストスイート（2,700+ tests）でこのパッケージを使用すると、OpenApiSpecLoader::$cache にデコードされたJSON specが静的に保持され、テスト全体を通じてメモリから解放されません。

当プロジェクトでは front.json（5.5MB）をデコードした PHP 配列だけで 約16MB を消費しており、extension全体で 約20MB のメモリオーバーヘッドが発生しています。

通常実行:          515.50 MB
--no-extensions:   495.50 MB
差分:              ~20 MB

Root Cause

OpenApiSpecLoader の $cache が static array で保持されており、一度ロードされたspecはプロセス終了まで解放されません。

// OpenApiSpecLoader.php
private static array $cache = [];

public static function load(string $specName): array
{
    if (isset(self::$cache[$specName])) {
        return self::$cache[$specName];
    }
    // ... file_get_contents + json_decode ...
    self::$cache[$specName] = $decoded;
    return $decoded;
}

加えて、OpenApiResponseValidator がアサーションごとに新規インスタンスを生成し、OpenApiPathMatcher がその都度正規表現をコンパイルしています。

Suggestions

1. WeakReference / オンデマンドロード: specを WeakReference で保持するか、バリデーション完了後にキャッシュをクリアするオプションを提供する

2. PathMatcher の再利用: OpenApiPathMatcher をspec単位でキャッシュし、毎回の正規表現コンパイルを避ける

3. 必要な部分だけロード: バリデーション対象のエンドポイントに必要なスキーマだけを抽出し、spec全体をメモリに保持しない（lazy loading）

4. spec キャッシュの手動クリアAPI: OpenApiSpecLoader::reset() は存在するが自動的に呼ばれない。テストクラス間でリセットするオプションを提供する

Environment

• PHP 8.4
• PHPUnit 13.0.5
• openapi-contract-testing v0.10.0
• front.json: 5.5MB (144,497 lines)

[wadakatu]

Analysis of each suggestion

1. WeakReference / on-demand loading → Not feasible

PHP's WeakReference only works with objects (class instances), not arrays. Since json_decode($json, true) returns arrays, WeakReference cannot be applied. Switching to json_decode($json, false) (stdClass) would be a breaking change for all consumers that use array access ($spec['paths'], etc.). On-demand loading is already how load() works (lazy load on first call + cache).

2. PathMatcher reuse → Already implemented (PR #36)

Commit c2c34bc caches PathMatcher, opis Validator, and ErrorFormatter instances per-spec in OpenApiResponseValidator. Regex compilation happens only once per spec via ??= lazy initialization.

3. Lazy loading (load only needed parts) → Not practical in PHP

PHP's json_decode() always parses the entire string — there is no built-in streaming/partial decode. Adding a streaming JSON parser (e.g., halaxa/json-machine) as a dependency is too heavy for a test library. A "decode then unset unused keys" approach doesn't reduce peak memory (the full array is already in memory during json_decode), and PHP doesn't return freed internal heap memory to the OS.

4. Manual cache clear API → Already implemented (PR #35)

Commit a97e22b added clearCache() and evict() to OpenApiSpecLoader. The OpenApiCoverageExtension already calls clearCache() automatically after coverage computation.

Summary

Suggestion	Status	Reason
1. WeakReference	Not feasible	PHP WeakReference doesn't support arrays
2. PathMatcher reuse	Already done	PR #36
3. Lazy loading	Not practical	json_decode always parses full input; no peak memory reduction
4. Cache clear API	Already done	PR #35

No further action needed. Closing.