# 機能設計書：HTTPリクエスト

## 1. 機能概要

### 1.1 機能名
HTTPリクエスト（HTTP Request）

### 1.2 機能説明
HTTPリクエストを抽象化し、URL、パス、クエリパラメータ、入力データ、ヘッダー、ファイル、セッション等へのアクセスを提供する機能。Symfony HttpFoundation の Request クラスを継承し、Laravel 独自の便利なメソッドを追加している。

### 1.3 関連画面
- 全画面（HTTPリクエストを処理するすべての機能で使用）

## 2. 機能詳細

### 2.1 処理フロー

```
[ブラウザ/APIクライアント]
       |
       v
[Web Server (Apache/Nginx)]
       |
       v
[index.php]
       |
       v
[Request::capture()] ──作成──> [Request インスタンス]
       |
       v
[Router / Middleware]
       |
       v
[Controller]
       |
       +-- $request->input()
       +-- $request->file()
       +-- $request->user()
       +-- etc.
```

### 2.2 クラス構成

| クラス名 | 役割 |
|---------|------|
| Request | メインリクエストクラス |
| SymfonyRequest | 基底クラス（Symfony HttpFoundation） |
| UploadedFile | アップロードファイルのラッパー |
| InputBag | 入力データのコンテナ |

### 2.3 主要メソッド

#### URL / パス関連

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `url()` | クエリ文字列を除いたURL | - | `string` |
| `fullUrl()` | クエリ文字列を含むURL | - | `string` |
| `path()` | パス情報 | - | `string` |
| `segment()` | パスセグメント取得 | `$index, $default` | `string\|null` |
| `is()` | パスパターンマッチ | `...$patterns` | `bool` |
| `routeIs()` | ルート名パターンマッチ | `...$patterns` | `bool` |
| `uri()` | Uriインスタンス取得 | - | `Uri` |

#### 入力データ関連

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `input()` | 入力値取得 | `$key, $default` | `mixed` |
| `query()` | クエリパラメータ取得 | `$key, $default` | `mixed` |
| `post()` | POSTデータ取得 | `$key, $default` | `mixed` |
| `all()` | 全入力データ取得 | - | `array` |
| `only()` | 指定キーのみ取得 | `$keys` | `array` |
| `except()` | 指定キー以外を取得 | `$keys` | `array` |
| `has()` | 入力存在チェック | `$key` | `bool` |
| `filled()` | 入力値が空でないかチェック | `$key` | `bool` |
| `merge()` | 入力データをマージ | `$input` | `$this` |
| `collect()` | Collectionとして取得 | `$key` | `Collection` |

#### ファイル関連

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `file()` | アップロードファイル取得 | `$key` | `UploadedFile\|null` |
| `hasFile()` | ファイル存在チェック | `$key` | `bool` |
| `allFiles()` | 全ファイル取得 | - | `array` |

#### リクエスト情報

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `method()` | HTTPメソッド取得 | - | `string` |
| `ip()` | クライアントIP取得 | - | `string\|null` |
| `ips()` | 全クライアントIP取得 | - | `array` |
| `userAgent()` | User-Agent取得 | - | `string\|null` |
| `header()` | ヘッダー取得 | `$key, $default` | `string\|null` |
| `bearerToken()` | Bearerトークン取得 | - | `string\|null` |
| `ajax()` | AJAXリクエスト判定 | - | `bool` |
| `pjax()` | PJAXリクエスト判定 | - | `bool` |
| `secure()` | HTTPS判定 | - | `bool` |
| `prefetch()` | プリフェッチ判定 | - | `bool` |

#### 認証 / セッション

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `user()` | 認証ユーザー取得 | `$guard` | `mixed` |
| `session()` | セッション取得 | - | `SessionInterface` |
| `old()` | 古い入力値取得 | `$key, $default` | `mixed` |
| `flash()` | 入力をフラッシュ | `$filter, $keys` | `void` |

### 2.4 ビジネスルール

1. **リクエストキャプチャルール**
   - `capture()` でグローバル変数からリクエスト生成
   - `enableHttpMethodParameterOverride()` でメソッドオーバーライド有効化
   - `_method` パラメータで PUT/PATCH/DELETE を偽装可能

2. **入力データ取得ルール**
   - `input()` は全ソース（query, post, json）から取得
   - `query()` はクエリパラメータのみ
   - `post()` はPOSTボディのみ
   - ドット記法でネストアクセス可能

3. **JSON リクエストルール**
   - Content-Type が `application/json` の場合、自動でJSONパース
   - `json()` メソッドで明示的にJSONアクセス

4. **バリデーションルール**
   - `validate()` メソッドで入力バリデーション（マクロ経由）
   - `validateWithBag()` でエラーバッグ指定

## 3. 入出力仕様

### 3.1 入力

| 項目 | 型 | 説明 |
|-----|-----|------|
| $_GET | `array` | クエリパラメータ |
| $_POST | `array` | POSTデータ |
| $_FILES | `array` | アップロードファイル |
| $_SERVER | `array` | サーバー変数 |
| php://input | `string` | リクエストボディ |

### 3.2 出力

| 項目 | 型 | 説明 |
|-----|-----|------|
| input | `mixed` | 入力データ |
| files | `UploadedFile[]` | アップロードファイル |
| headers | `array` | HTTPヘッダー |

## 4. 依存関係

### 4.1 内部依存

| パッケージ | 用途 |
|-----------|------|
| Illuminate\Support\Arr | 配列操作 |
| Illuminate\Support\Str | 文字列操作 |
| Illuminate\Support\Collection | コレクション |
| Illuminate\Support\Uri | URI操作 |
| Illuminate\Http\UploadedFile | ファイルラッパー |

### 4.2 外部依存

| パッケージ | 用途 |
|-----------|------|
| symfony/http-foundation | 基底クラス |

## 5. エラー処理

| エラー種別 | 発生条件 | 処理内容 |
|-----------|---------|---------|
| SessionNotFoundException | セッション未設定 | 例外スロー |
| RuntimeException | ルート未解決 | 例外スロー |
| JsonException | JSONパース失敗 | 例外スロー |

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

### 6.1 推奨読解順序

1. **クラス定義とトレイト** (`Http/Request.php`)
   - **29-36行目**: クラス定義と使用トレイト
     - `CanBePrecognitive`: Precognition リクエスト対応
     - `InteractsWithContentTypes`: Content-Type 判定
     - `InteractsWithFlashData`: フラッシュデータ操作
     - `InteractsWithInput`: 入力データ操作
     - `Conditionable`: 条件付きメソッドチェーン
     - `Macroable`: マクロ拡張

2. **リクエストキャプチャ**
   - **78-83行目**: `capture()` メソッド - グローバル変数からリクエスト生成

3. **URL / パス取得メソッド**
   - **100-103行目**: `method()` - HTTPメソッド取得
   - **110-113行目**: `uri()` - Uriインスタンス生成
   - **130-133行目**: `url()` - クエリなしURL
   - **140-147行目**: `fullUrl()` - 完全URL
   - **186-191行目**: `path()` - パス情報

4. **パターンマッチ**
   - **235-239行目**: `is()` - パスパターンマッチ
   - **247-250行目**: `routeIs()` - ルート名マッチ

5. **リクエスト情報取得**
   - **299-302行目**: `ajax()` - AJAX判定
   - **309-312行目**: `pjax()` - PJAX判定
   - **331-334行目**: `secure()` - HTTPS判定
   - **341-344行目**: `ip()` - クライアントIP

6. **入力データ操作**
   - **389-398行目**: `merge()` - 入力データマージ

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

```
Request::capture()
└── SymfonyRequest::createFromGlobals()
    └── Request::createFromBase()
        └── new Request()

$request->input('key')
└── InteractsWithInput::input()
    └── Arr::get($this->all(), $key)
        └── InteractsWithInput::all()
            └── array_merge($this->query(), $this->post(), $this->json())

$request->user()
└── Request::user()
    └── $this->userResolver()
        └── Auth::user()
```

### 6.3 データフロー図

```
[HTTP Request]
    |
    v
[PHP グローバル変数]
  $_GET, $_POST, $_FILES, $_SERVER, php://input
    |
    v
[Request::capture()]
    |
    v
[Request インスタンス]
    |
    +-- query: QueryBag (GET パラメータ)
    +-- request: InputBag (POST パラメータ)
    +-- files: FileBag (アップロードファイル)
    +-- cookies: InputBag (クッキー)
    +-- headers: HeaderBag (ヘッダー)
    +-- server: ServerBag (サーバー変数)
    |
    v
[Controller / Middleware で利用]
```

### 6.4 読解のコツ

- **Symfony 継承**: `SymfonyRequest` を継承し、Laravel 独自のメソッドを追加
- **トレイト分離**: 機能ごとにトレイトに分離（`Concerns/` ディレクトリ）
- **マジックメソッド**: `__get()` で動的プロパティアクセス対応
- **Macroable**: `validate()` 等はマクロとして追加される

### 6.5 関連ファイル一覧

| ファイルパス | 種別 | 役割 |
|------------|------|------|
| `src/Illuminate/Http/Request.php` | Request | メインリクエストクラス |
| `src/Illuminate/Http/Concerns/CanBePrecognitive.php` | Trait | Precognition対応 |
| `src/Illuminate/Http/Concerns/InteractsWithContentTypes.php` | Trait | Content-Type判定 |
| `src/Illuminate/Http/Concerns/InteractsWithFlashData.php` | Trait | フラッシュデータ |
| `src/Illuminate/Http/Concerns/InteractsWithInput.php` | Trait | 入力データ操作 |
| `src/Illuminate/Http/UploadedFile.php` | File | アップロードファイルラッパー |
| `src/Illuminate/Support/Uri.php` | Uri | URI操作 |

## 7. 使用例

```php
use Illuminate\Http\Request;

// コントローラでの使用
class UserController extends Controller
{
    public function store(Request $request)
    {
        // 入力データ取得
        $name = $request->input('name');
        $email = $request->input('email', 'default@example.com');

        // 全入力取得
        $all = $request->all();

        // 特定キーのみ取得
        $userData = $request->only(['name', 'email']);

        // ファイルアップロード
        if ($request->hasFile('avatar')) {
            $path = $request->file('avatar')->store('avatars');
        }

        // URL情報
        $url = $request->url();
        $fullUrl = $request->fullUrl();
        $path = $request->path();

        // リクエスト情報
        $method = $request->method();
        $ip = $request->ip();
        $userAgent = $request->userAgent();

        // 認証ユーザー
        $user = $request->user();

        // パスパターンマッチ
        if ($request->is('admin/*')) {
            // 管理画面へのリクエスト
        }

        // ルート名パターンマッチ
        if ($request->routeIs('users.*')) {
            // ユーザー関連ルート
        }

        // バリデーション
        $validated = $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|email',
        ]);
    }
}
```

## 8. 改版履歴

| バージョン | 日付 | 変更内容 |
|-----------|------|---------|
| 1.0.0 | - | 初版作成 |
