# 機能設計書 49-Cookie管理

## 概要

本ドキュメントは、Laravel FrameworkのCookie管理機能の設計仕様を定義する。CookieJarクラスを中心とした、HTTPクッキーの生成・キュー管理機能について詳述する。

### 本機能の処理概要

Cookie管理は、HTTPレスポンスに付与するCookieの生成とキュー管理を行う。Symfony HttpFoundationのCookieクラスをベースに、Laravelアプリケーション向けのファクトリメソッドとキュー機構を提供する。

**業務上の目的・背景**：Cookieはユーザー認証状態の維持、セッション管理、ユーザー設定の保存など、様々な目的で使用される。Cookie管理機能により、セキュアなCookieの生成（SameSite、Secure、HttpOnly設定）、有効期限管理、パス/ドメイン設定が容易になり、セキュリティベストプラクティスに沿ったCookie運用が可能になる。

**機能の利用シーン**：ユーザー認証Cookieの発行、Remember Me機能、CSRF保護トークンの設定、ユーザー設定の保存、トラッキング用Cookieの発行などで利用される。

**主要な処理内容**：
1. Cookieインスタンスの生成（make）
2. 永続的Cookie（forever）の生成
3. Cookie削除用Cookieの生成（forget）
4. Cookieのキュー管理（queue、unqueue）
5. デフォルト設定の管理（path、domain、secure、sameSite）

**関連システム・外部連携**：HTTPレスポンス、セッション管理、認証システム、CSRF保護と連携する。

**権限による制御**：Cookie管理自体には権限制御は存在しないが、Cookieの内容に応じた認証・認可処理が別途行われる。

## 関連画面

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

## 機能種別

HTTP管理 / セッション管理補助

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | Cookie名 | - |
| value | string | No | Cookie値 | - |
| minutes | int | No | 有効期限（分）、0で永続Cookie | - |
| path | string\|null | No | パス（デフォルト: /） | - |
| domain | string\|null | No | ドメイン | - |
| secure | bool\|null | No | Secure属性 | - |
| httpOnly | bool | No | HttpOnly属性（デフォルト: true） | - |
| raw | bool | No | URLエンコードをスキップするか | - |
| sameSite | string\|null | No | SameSite属性（lax/strict/none） | - |

### 入力データソース

- アプリケーションコードからの直接呼び出し
- 認証システムからのCookie発行リクエスト
- ミドルウェアからのCookie操作

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| cookie | Cookie | Symfony\Component\HttpFoundation\Cookieインスタンス |

### 出力先

- HTTPレスポンス（AddQueuedCookiesToResponseミドルウェア経由）

## 処理フロー

### 処理シーケンス

```
1. Cookie生成リクエスト
   └─ make()またはforever()、forget()メソッド呼び出し

2. デフォルト値適用
   └─ getPathAndDomain()でデフォルトpath、domain、secure、sameSiteを適用

3. 有効期限計算
   └─ availableAt()で有効期限タイムスタンプを計算

4. Cookieインスタンス生成
   └─ Symfony\Component\HttpFoundation\Cookieを生成

5. キュー登録（オプション）
   └─ queue()でキューに追加
```

### フローチャート

```mermaid
flowchart TD
    A[Cookie操作リクエスト] --> B{操作種別}
    B -->|make| C[make メソッド]
    B -->|forever| D[forever メソッド]
    B -->|forget| E[forget メソッド]
    B -->|queue| F[queue メソッド]
    C --> G[getPathAndDomain]
    D --> H[make 576000分]
    E --> I[make -2628000分]
    H --> G
    I --> G
    G --> J[availableAt で有効期限計算]
    J --> K[new Cookie]
    K --> L{キュー追加?}
    L -->|Yes| M[queued配列に追加]
    L -->|No| N[Cookie返却]
    F --> O{Cookieインスタンス?}
    O -->|Yes| P[そのままキュー追加]
    O -->|No| Q[make でCookie生成]
    Q --> P
    P --> M
    M --> R[完了]
    N --> R
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-49-1 | 永続Cookie | forever()は576000分（400日）の有効期限を設定 | forever()呼び出し時 |
| BR-49-2 | Cookie削除 | forget()は負の有効期限（-2628000分）を設定して削除 | forget()呼び出し時 |
| BR-49-3 | デフォルトSameSite | sameSiteのデフォルトは'lax' | sameSite未指定時 |
| BR-49-4 | HttpOnlyデフォルト | httpOnlyのデフォルトはtrue | httpOnly未指定時 |
| BR-49-5 | パス別キュー | 同名Cookieでもパスが異なれば別々にキュー管理 | queue()時 |

### 計算ロジック

| 計算名 | 計算式 | 説明 |
|--------|-------|------|
| 有効期限 | minutes == 0 ? 0 : availableAt(minutes * 60) | 分単位から秒に変換、0はセッションCookie |

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | Cookie管理自体はデータベース操作を行わない |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | Cookie管理では特別なエラー処理は行わない |

### リトライ仕様

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

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

Cookie管理はトランザクション管理を行わない。

## パフォーマンス要件

- Cookieキューはメモリ内で管理され、オーバーヘッドは最小限
- レスポンス送信時に一括でCookieヘッダーを付与

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

- センシティブな情報はCookieに直接保存せず、暗号化を検討
- HttpOnly属性を有効にしてJavaScriptからのアクセスを防止
- Secure属性を有効にしてHTTPS接続時のみ送信
- SameSite属性でCSRF攻撃を緩和

## 備考

- cookie()ヘルパー関数で利用可能
- Macroableトレイトによる拡張が可能
- EncryptCookiesミドルウェアで自動暗号化

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: $pathと$domainがデフォルト設定、$secureと$sameSiteがセキュリティ設定、$queuedがキュー済みCookieのリスト。

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

Cookie生成の入口を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CookieJar.php | `src/Illuminate/Cookie/CookieJar.php` | make()（64-71行目）がCookie生成のメインメソッド |

**主要処理フロー**:
1. **66行目**: getPathAndDomain()でデフォルト値を適用
2. **68行目**: availableAt()で有効期限を計算
3. **70行目**: new Cookieでインスタンス生成

#### Step 3: 特殊Cookie生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CookieJar.php | `src/Illuminate/Cookie/CookieJar.php` | forever()（86-89行目） |
| 3-2 | CookieJar.php | `src/Illuminate/Cookie/CookieJar.php` | forget()（99-102行目） |

**主要処理フロー**:
- **88行目**: forever()は576000分（400日）でmake()を呼び出し
- **101行目**: forget()は-2628000分（約5年前）でmake()を呼び出し

#### Step 4: キュー管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | CookieJar.php | `src/Illuminate/Cookie/CookieJar.php` | queue()（141-154行目） |
| 4-2 | CookieJar.php | `src/Illuminate/Cookie/CookieJar.php` | queued()（124-133行目） |
| 4-3 | CookieJar.php | `src/Illuminate/Cookie/CookieJar.php` | unqueue()（176-189行目） |
| 4-4 | CookieJar.php | `src/Illuminate/Cookie/CookieJar.php` | getQueuedCookies()（226-229行目） |

**主要処理フロー**:
- **143-147行目**: Cookieインスタンスならそのまま、パラメータならmake()で生成
- **149-153行目**: $queued配列に名前とパスで格納
- **178-188行目**: unqueue()で指定パスまたは全パスを削除

#### Step 5: デフォルト設定管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | CookieJar.php | `src/Illuminate/Cookie/CookieJar.php` | getPathAndDomain()（200-203行目） |
| 5-2 | CookieJar.php | `src/Illuminate/Cookie/CookieJar.php` | setDefaultPathAndDomain()（214-219行目） |

**主要処理フロー**:
- **202行目**: 引数がnullならデフォルト値を返却
- **216行目**: デフォルト値を一括設定

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

```
cookie($name, $value, ...) [ヘルパー関数]
    │
    ├─ [引数なし] CookieJar インスタンス返却
    │
    └─ [引数あり] CookieJar::make($name, $value, ...)
           │
           ├─ getPathAndDomain($path, $domain, $secure, $sameSite)
           │      └─ デフォルト値の適用
           │
           ├─ availableAt($minutes * 60)
           │      └─ 有効期限タイムスタンプ計算
           │
           └─ new Symfony\Component\HttpFoundation\Cookie(...)
                  └─ Cookieインスタンス生成

CookieJar::forever($name, $value, ...)
    │
    └─ make($name, $value, 576000, ...)
           └─ 400日後を有効期限としたCookie

CookieJar::forget($name, ...)
    │
    └─ make($name, null, -2628000, ...)
           └─ 過去日時を有効期限としたCookie（削除用）

CookieJar::queue($cookie)
    │
    ├─ [Cookieインスタンス] そのまま使用
    │
    └─ [パラメータ] make(...) で生成
           │
           └─ $queued[$name][$path] = $cookie
```

### データフロー図

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

$name,$value,... ───▶  make()                   ───▶  Cookie
(Cookie情報)            (Cookie生成)

$path,$domain,.. ───▶  getPathAndDomain()       ───▶  [$path,$domain,$secure,$sameSite]
(設定またはnull)        (デフォルト適用)

$minutes         ───▶  availableAt()            ───▶  タイムスタンプ
(有効期限:分)           (期限計算)

Cookie           ───▶  queue()                  ───▶  $queued配列に追加
(Cookieインスタンス)    (キュー登録)

$queued          ───▶  getQueuedCookies()       ───▶  Cookie配列
(キューデータ)          (フラット化)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CookieJar.php | `src/Illuminate/Cookie/CookieJar.php` | ソース | Cookie管理のメイン実装 |
| CookieServiceProvider.php | `src/Illuminate/Cookie/CookieServiceProvider.php` | ソース | サービスプロバイダ |
| AddQueuedCookiesToResponse.php | `src/Illuminate/Cookie/Middleware/AddQueuedCookiesToResponse.php` | ソース | キュー済みCookieをレスポンスに付与 |
| EncryptCookies.php | `src/Illuminate/Cookie/Middleware/EncryptCookies.php` | ソース | Cookie暗号化ミドルウェア |
| QueueingFactory.php | `src/Illuminate/Contracts/Cookie/QueueingFactory.php` | コントラクト | キューイングファクトリインターフェース |
| Factory.php | `src/Illuminate/Contracts/Cookie/Factory.php` | コントラクト | ファクトリインターフェース |
