# 機能設計書 48-Redis管理

## 概要

本ドキュメントは、Laravel FrameworkのRedis管理機能の設計仕様を定義する。RedisManagerクラスを中心とした、Redisコネクション管理・操作機能について詳述する。

### 本機能の処理概要

Redis管理は、Redisサーバーへの接続管理と操作のための統一インターフェースを提供する。Predis（PHPベースのクライアント）とPhpRedis（PHPエクステンション）の両方をサポートし、接続プール管理、クラスター対応、イベント発火機能を備える。

**業務上の目的・背景**：Redisは高速なインメモリデータストアとして、キャッシュ、セッション管理、キュー、リアルタイム通信など様々な用途で利用される。Redis管理機能により、これらの機能を統一的なAPIで利用でき、ドライバの切り替えも容易になる。

**機能の利用シーン**：キャッシュの読み書き、セッションデータの保存、キュージョブの管理、ブロードキャストメッセージの配信、レート制限のカウンタ管理などで利用される。

**主要な処理内容**：
1. Redisコネクションの管理
2. 単一サーバー・クラスター対応
3. PredisとPhpRedisの両ドライバサポート
4. コネクションイベントの発火
5. カスタムドライバの登録

**関連システム・外部連携**：Redisサーバー、キャッシュシステム、セッションシステム、キューシステム、ブロードキャストシステムと連携する。

**権限による制御**：Redis管理自体には権限制御は存在しないが、Redisサーバーの認証設定（AUTH）により接続を制御する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面機能マッピングにRedis管理関連の画面なし |

## 機能種別

データストア接続 / 接続管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string\|UnitEnum\|null | No | コネクション名（null時は'default'） | 設定済みコネクション名 |

### 入力データソース

- 設定ファイル（config/database.php redis セクション）
- アプリケーションコードからの直接呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| connection | Connection | Redisコネクションインスタンス |
| command result | mixed | Redisコマンドの実行結果 |

### 出力先

- 呼び出し元への戻り値

## 処理フロー

### 処理シーケンス

```
1. コネクション要求
   └─ connection()メソッドでコネクション名を指定

2. キャッシュ確認
   └─ $connectionsから既存コネクションを検索

3. コネクション解決
   └─ resolve()で設定を読み込みコネクション作成

4. コネクター取得
   └─ connector()でドライバに応じたコネクター取得

5. 接続実行
   └─ connect()またはconnectToCluster()で接続

6. コネクション設定
   └─ configure()で名前設定、イベントディスパッチャ設定

7. キャッシュ登録
   └─ $connectionsにコネクションを保存
```

### フローチャート

```mermaid
flowchart TD
    A[connection要求] --> B{コネクション名}
    B --> C[enum_value で名前解決]
    C --> D{キャッシュ済み?}
    D -->|Yes| E[キャッシュから返却]
    D -->|No| F[resolve 実行]
    F --> G{設定あり?}
    G -->|単一| H[connector->connect]
    G -->|クラスター| I[resolveCluster]
    G -->|なし| J[InvalidArgumentException]
    H --> K[configure]
    I --> K
    K --> L[キャッシュに保存]
    L --> M[コネクション返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-48-1 | デフォルトコネクション | nameがnullの場合は'default'コネクションを使用 | connection(null) |
| BR-48-2 | ドライバ選択 | predisまたはphpredisドライバを設定に応じて使用 | config.driver |
| BR-48-3 | イベント発火 | enableEvents()呼び出し後、コマンド実行時にイベント発火 | $events = true |
| BR-48-4 | URL解析 | 接続URLが指定された場合は自動解析 | ConfigurationUrlParser使用 |

### 計算ロジック

該当なし

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

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | Redis管理はRDBMSではなくRedisを操作 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidArgumentException | コネクション未設定 | 指定されたコネクションが設定されていない | config/database.phpにコネクションを追加 |
| ConnectionException | 接続失敗 | Redisサーバーに接続できない | サーバーアドレス、ポート、認証情報を確認 |

### リトライ仕様

リトライ処理はRedisManagerでは実装されていない。

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

RedisのMULTI/EXEC/DISCARDによるトランザクションは、Connectionクラスで提供される。

## パフォーマンス要件

- コネクションは$connectionsにキャッシュされ、同一リクエスト内で再利用
- PhpRedisはPredisより高速だが、PHPエクステンションのインストールが必要

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

- Redisの認証（AUTH）を有効にすることを推奨
- 外部からの直接アクセスを防ぐためファイアウォール設定を実施
- TLS接続をサポート

## 備考

- Redis::connection()またはRedisファサードで利用
- PhpRedisの場合、非同期操作もサポート

---

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

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

### 推奨読解順序

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

RedisManagerが管理する内部状態を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | RedisManager.php | `src/Illuminate/Redis/RedisManager.php` | プロパティ定義（26-61行目）で管理される状態を把握 |
| 1-2 | Factory.php | `src/Illuminate/Contracts/Redis/Factory.php` | インターフェース定義 |

**読解のコツ**: $driverで使用するドライバ（predis/phpredis）、$configで接続設定、$connectionsで解決済みコネクションを管理。

#### Step 2: エントリーポイントを理解する

コネクション取得の入口を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | RedisManager.php | `src/Illuminate/Redis/RedisManager.php` | connection()（83-94行目）がメインエントリー |

**主要処理フロー**:
1. **85行目**: enum_valueで名前を文字列に変換
2. **87-88行目**: キャッシュ済みならそれを返却
3. **91-93行目**: resolve()で解決し、configure()で設定してキャッシュ

#### Step 3: コネクション解決処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | RedisManager.php | `src/Illuminate/Redis/RedisManager.php` | resolve()（104-122行目） |
| 3-2 | RedisManager.php | `src/Illuminate/Redis/RedisManager.php` | resolveCluster()（130-139行目） |
| 3-3 | RedisManager.php | `src/Illuminate/Redis/RedisManager.php` | connector()（164-177行目） |

**主要処理フロー**:
- **108行目**: optionsを取得
- **110-114行目**: 単一サーバー設定の場合はconnector()->connect()
- **117-118行目**: クラスター設定の場合はresolveCluster()
- **121行目**: どちらもない場合はInvalidArgumentException
- **172-176行目**: predisならPredisConnector、phpredisならPhpRedisConnector

#### Step 4: コネクター実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | PredisConnector.php | `src/Illuminate/Redis/Connectors/PredisConnector.php` | Predis接続ロジック |
| 4-2 | PhpRedisConnector.php | `src/Illuminate/Redis/Connectors/PhpRedisConnector.php` | PhpRedis接続ロジック |

**主要処理フロー**:
- **PredisConnector::connect()**: Predis\Clientインスタンスを作成
- **PhpRedisConnector::connect()**: Redis PHPエクステンションを使用して接続

#### Step 5: Connectionクラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Connection.php | `src/Illuminate/Redis/Connections/Connection.php` | 基底接続クラス |
| 5-2 | PredisConnection.php | `src/Illuminate/Redis/Connections/PredisConnection.php` | Predis接続実装 |
| 5-3 | PhpRedisConnection.php | `src/Illuminate/Redis/Connections/PhpRedisConnection.php` | PhpRedis接続実装 |

**主要処理フロー**:
- **Connection::command()**: コマンド実行と時間測定、イベント発火
- **Connection::client()**: 実際のRedisクライアント取得

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

```
Redis::connection($name) [ファサード]
    │
    └─ RedisManager::connection($name)
           │
           ├─ [キャッシュあり] $connections[$name]
           │
           └─ [キャッシュなし]
              ├─ resolve($name)
              │      │
              │      ├─ connector()
              │      │      │
              │      │      ├─ [predis] new PredisConnector
              │      │      │
              │      │      └─ [phpredis] new PhpRedisConnector
              │      │
              │      ├─ [単一] connector->connect($config, $options)
              │      │      │
              │      │      ├─ parseConnectionConfiguration()
              │      │      │
              │      │      └─ new PredisConnection / PhpRedisConnection
              │      │
              │      └─ [クラスター] resolveCluster($name)
              │             └─ connector->connectToCluster($configs, $options)
              │
              └─ configure($connection, $name)
                     │
                     ├─ setName($name)
                     │
                     └─ setEventDispatcher() [events=true時]
```

### データフロー図

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

$name            ───▶  connection()             ───▶  Connection
(コネクション名)         (コネクション取得)

$config          ───▶  parseConnectionConfiguration() ───▶ 解析済み設定
(接続設定)              (URL/設定解析)

$config,$options ───▶  connector->connect()     ───▶  Connection
(接続設定)              (実際の接続)

Connection       ───▶  configure()              ───▶  設定済みConnection
(未設定接続)            (名前、イベント設定)

$command         ───▶  Connection::command()    ───▶  コマンド結果
(Redisコマンド)         (コマンド実行)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| RedisManager.php | `src/Illuminate/Redis/RedisManager.php` | ソース | Redis管理のメイン実装 |
| RedisServiceProvider.php | `src/Illuminate/Redis/RedisServiceProvider.php` | ソース | サービスプロバイダ |
| Connection.php | `src/Illuminate/Redis/Connections/Connection.php` | ソース | 接続基底クラス |
| PredisConnection.php | `src/Illuminate/Redis/Connections/PredisConnection.php` | ソース | Predis接続実装 |
| PhpRedisConnection.php | `src/Illuminate/Redis/Connections/PhpRedisConnection.php` | ソース | PhpRedis接続実装 |
| PredisConnector.php | `src/Illuminate/Redis/Connectors/PredisConnector.php` | ソース | Predisコネクター |
| PhpRedisConnector.php | `src/Illuminate/Redis/Connectors/PhpRedisConnector.php` | ソース | PhpRedisコネクター |
| Factory.php | `src/Illuminate/Contracts/Redis/Factory.php` | コントラクト | ファクトリインターフェース |
| Connector.php | `src/Illuminate/Contracts/Redis/Connector.php` | コントラクト | コネクターインターフェース |
