# 機能設計書 10-キャッシュ管理

## 概要

本ドキュメントは、Laravel Frameworkのキャッシュ管理機能について、その設計思想、処理フロー、および実装詳細を記述したものである。CacheManagerを中心とした複数キャッシュドライバのサポートと統一的なキャッシュ操作APIの設計を定義する。

### 本機能の処理概要

キャッシュ管理機能は、File、Redis、Memcached、Database、DynamoDB、APCなど多様なキャッシュストアへの統一的なアクセスを提供する機能である。キャッシュの読み書き、有効期限管理、タグ付けキャッシュなどをサポートする。

**業務上の目的・背景**：データベースや外部APIへの頻繁なアクセスはパフォーマンスに悪影響を与える。キャッシュはこれらのアクセスを削減し、レスポンス時間の短縮とシステム負荷の軽減を実現する。また、複数のキャッシュバックエンドを統一的に扱えることで、環境に応じた最適なキャッシュ戦略を選択できる。

**機能の利用シーン**：
- データベースクエリ結果のキャッシュ
- 外部API呼び出し結果のキャッシュ
- 設定値やマスターデータのキャッシュ
- セッションストレージ
- ルートキャッシュ、設定キャッシュ
- レート制限

**主要な処理内容**：
1. キャッシュストアの解決とインスタンス管理
2. get/put/forget等の基本操作
3. 有効期限（TTL）管理
4. タグ付けキャッシュ
5. アトミック操作（increment/decrement）
6. ロック機能
7. キャッシュイベントの発火

**関連システム・外部連携**：
- Redis（phpredis/predis）
- Memcached
- Database（cache/cache_locksテーブル）
- DynamoDB
- Filesystem
- Event Dispatcher（キャッシュイベント）

**権限による制御**：キャッシュ管理自体は権限制御を行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 47 | キャッシュコンポーネント | 補助機能 | キャッシュ統計情報の表示連携 |

## 機能種別

インフラストラクチャ / キャッシュ / パフォーマンス最適化

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| key | string | Yes | キャッシュキー | - |
| value | mixed | No | キャッシュ値（put時） | シリアライズ可能 |
| ttl | int\|DateTimeInterface | No | 有効期限（秒またはDateTime） | - |
| store | string | No | 使用するストア名 | config定義済み |

### 入力データソース

- アプリケーションコード（Cache::get()等）
- config/cache.php（ストア設定）
- 環境変数（CACHE_DRIVER等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| value | mixed | キャッシュから取得した値 |
| success | bool | 操作成功/失敗 |

### 出力先

- アプリケーションコード
- キャッシュストア（Redis、ファイル等）
- Event Dispatcher（キャッシュイベント）

## 処理フロー

### 処理シーケンス

```
1. ストア解決
   └─ store($name)でストアインスタンスを取得（キャッシュ優先）
2. リポジトリ取得
   └─ Repository（キャッシュ操作のラッパー）を取得
3. 操作実行
   └─ get/put/forget等の操作をStoreに委譲
4. イベント発火
   └─ CacheHit/CacheMissed等のイベント
```

### フローチャート

```mermaid
flowchart TD
    A[Cache::get($key)] --> B[CacheManager::store()]
    B --> C{キャッシュあり?}
    C -->|Yes| D[stores[$name]返却]
    C -->|No| E[resolve($name)]
    E --> F[getConfig($name)]
    F --> G{カスタムドライバ?}
    G -->|Yes| H[callCustomCreator()]
    G -->|No| I[create{Driver}Driver()]
    H --> J[repository()でラップ]
    I --> J
    J --> K[stores[$name]に保存]
    K --> L[Repository::get($key)]
    L --> M[Store::get($key)]
    M --> N{値あり?}
    N -->|Yes| O[CacheHitイベント]
    N -->|No| P[CacheMissedイベント]
    O --> Q[値返却]
    P --> R[default返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | デフォルトストア | config('cache.default')で指定されたストアを使用 | store()引数なし時 |
| BR-02 | 永続キャッシュ | TTL=null または foreverで永続化 | forever()呼び出し時 |
| BR-03 | シリアライズ | 値はシリアライズして保存（設定で許可クラス制限可） | put()時 |
| BR-04 | プレフィックス | キーにプレフィックスを付加（名前空間分離） | 全操作 |
| BR-05 | Failover | failoverドライバで複数ストアのフェイルオーバー | failover設定時 |

### 計算ロジック

- プレフィックス付きキー: `prefix:key`
- TTL計算: DateTimeInterface指定時は現在時刻からの差分秒数

## データベース操作仕様

### 操作別データベース影響一覧（Databaseドライバ使用時）

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| get() | cache | SELECT | キーで値を取得 |
| put() | cache | INSERT/UPDATE | キーと値を保存 |
| forget() | cache | DELETE | キーを削除 |
| flush() | cache | DELETE | 全キャッシュ削除 |

### テーブル別操作詳細

#### cacheテーブル（Databaseドライバ）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | key, value, expiration | key = ? | get時 |
| INSERT | key, value, expiration | キー、シリアライズ値、有効期限 | put時 |
| DELETE | key | key = ? | forget時 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidArgumentException | 未定義のストア名 | config/cache.phpを確認 |
| - | InvalidArgumentException | 未サポートのドライバ | ドライバ名を確認 |
| - | ConnectionException | Redis/Memcached接続失敗 | 接続設定を確認 |

### リトライ仕様

failoverドライバで複数ストアへのフェイルオーバーをサポート。

## トランザクション仕様

キャッシュ操作にトランザクションはない。Databaseドライバもトランザクション外で動作。

## パフォーマンス要件

- ストアインスタンスはリクエスト内でキャッシュ
- Redis/Memcachedは永続接続を推奨
- 大きな値の保存は避ける

## セキュリティ考慮事項

- シリアライズ時のクラス制限（serializable_classes設定）
- キャッシュキーのサニタイズ
- Redis認証（パスワード設定）

## 備考

- `Cache::remember($key, $ttl, $callback)`で遅延評価キャッシュ
- `Cache::lock($name)->get()`で排他制御
- `Cache::tags(['tag1', 'tag2'])->put()`でタグ付けキャッシュ
- memo()でリクエスト内メモ化キャッシュ

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Factory.php | `src/Illuminate/Contracts/Cache/Factory.php` | キャッシュファクトリインターフェース |
| 1-2 | Store.php | `src/Illuminate/Contracts/Cache/Store.php` | ストアインターフェース |
| 1-3 | Repository.php | `src/Illuminate/Contracts/Cache/Repository.php` | リポジトリインターフェース |

**読解のコツ**: CacheManagerがFactory、RepositoryがキャッシュのメインAPI、StoreがバックエンドのI/Fという階層を理解する。

#### Step 2: CacheManagerを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CacheManager.php | `src/Illuminate/Cache/CacheManager.php` | キャッシュマネージャ本体 |

**主要処理フロー**:
- **47-50行目**: コンストラクタでapp注入
- **58-63行目**: store()でストア取得（キャッシュ優先）
- **82-99行目**: memo()でメモ化キャッシュ
- **109-120行目**: resolve()でストア解決
- **130-145行目**: build()でストア構築
- **164-169行目**: createApcDriver()
- **191-211行目**: createDatabaseDriver()
- **284-296行目**: createFileDriver()
- **334-351行目**: createRedisDriver()
- **395-402行目**: repository()でRepository生成
- **471-473行目**: getDefaultDriver()

#### Step 3: Repositoryを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Repository.php | `src/Illuminate/Cache/Repository.php` | キャッシュ操作のラッパー |

**読解ポイント**:
- get(): キャッシュ取得（イベント発火）
- put(): キャッシュ保存
- remember(): 遅延評価キャッシュ
- forget(): キャッシュ削除
- イベント発火ロジック

#### Step 4: 各Storeを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | RedisStore.php | `src/Illuminate/Cache/RedisStore.php` | Redisストア |
| 4-2 | FileStore.php | `src/Illuminate/Cache/FileStore.php` | ファイルストア |
| 4-3 | DatabaseStore.php | `src/Illuminate/Cache/DatabaseStore.php` | データベースストア |

### プログラム呼び出し階層図

```
Cache Facade / app('cache')
    │
    └─ CacheManager::store($name)
           │
           ├─ [キャッシュあり]
           │      └─ stores[$name] 返却
           │
           └─ [キャッシュなし]
                  │
                  └─ resolve($name)
                         │
                         ├─ getConfig($name)
                         │      └─ config["cache.stores.{$name}"]
                         │
                         └─ build($config)
                                │
                                ├─ customCreators[$driver] 存在時
                                │      └─ callCustomCreator()
                                │
                                └─ create{Driver}Driver()
                                       │
                                       ├─ createRedisDriver()
                                       │      └─ new RedisStore()
                                       │
                                       ├─ createFileDriver()
                                       │      └─ new FileStore()
                                       │
                                       └─ ... 他ドライバ
                                       │
                                       └─ repository($store, $config)
                                              └─ new Repository($store)
```

### データフロー図

```
[入力]                    [処理]                         [出力]

Cache::get($key) ──────▶ CacheManager ───────────────────▶ キャッシュ値
                              │
                              ▼
                        Repository
                              │
                              ├── get() ◀──────── Store::get()
                              │                       │
                              │                       ├─ Redis
                              │                       ├─ File
                              │                       ├─ Database
                              │                       └─ Memcached
                              │
                              └── イベント発火 ────────▶ Event Dispatcher
                                     │
                                     ├─ CacheHit
                                     ├─ CacheMissed
                                     ├─ KeyWritten
                                     └─ KeyForgotten
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CacheManager.php | `src/Illuminate/Cache/CacheManager.php` | ソース | キャッシュマネージャ |
| CacheServiceProvider.php | `src/Illuminate/Cache/CacheServiceProvider.php` | ソース | サービスプロバイダ |
| Repository.php | `src/Illuminate/Cache/Repository.php` | ソース | キャッシュリポジトリ |
| RedisStore.php | `src/Illuminate/Cache/RedisStore.php` | ソース | Redisストア |
| FileStore.php | `src/Illuminate/Cache/FileStore.php` | ソース | ファイルストア |
| DatabaseStore.php | `src/Illuminate/Cache/DatabaseStore.php` | ソース | データベースストア |
| MemcachedStore.php | `src/Illuminate/Cache/MemcachedStore.php` | ソース | Memcachedストア |
| ArrayStore.php | `src/Illuminate/Cache/ArrayStore.php` | ソース | 配列ストア（テスト用） |
| NullStore.php | `src/Illuminate/Cache/NullStore.php` | ソース | Nullストア |
| DynamoDbStore.php | `src/Illuminate/Cache/DynamoDbStore.php` | ソース | DynamoDBストア |
| TaggedCache.php | `src/Illuminate/Cache/TaggedCache.php` | ソース | タグ付けキャッシュ |
| Lock.php | `src/Illuminate/Cache/Lock.php` | ソース | ロック基底クラス |
| Events/ | `src/Illuminate/Cache/Events/` | ソース | キャッシュイベント群 |
