# 帳票設計書 2-BinaryFileResponse

## 概要

本ドキュメントは、Laravel FrameworkにおけるBinaryFileResponse（バイナリファイルレスポンス）機能の設計仕様を定義する。バイナリファイルをダウンロードするための帳票出力機能であり、PDF・Excel等のファイル出力に利用される。

### 本帳票の処理概要

BinaryFileResponseは、サーバー上の既存ファイルをHTTPレスポンスとして直接クライアントに送信する機能を提供する。ファイルの内容をメモリに読み込むことなく、ファイルシステムから直接ストリーミング出力するため、大容量ファイルでも効率的に処理できる。

**業務上の目的・背景**：業務システムにおいて、PDFの請求書、Excelの集計レポート、画像ファイル、ZIPアーカイブなど、様々なバイナリファイルをユーザーにダウンロードさせる必要がある。従来のファイル読み込み方式ではメモリ制限の問題が発生するが、BinaryFileResponseを使用することで、X-Sendfile機能と連携した高速なファイル配信や、部分ダウンロード（Range Request）にも対応できる。

**帳票の利用シーン**：
- PDF形式の請求書・見積書のダウンロード
- Excelレポートのエクスポート
- システムが生成した帳票ファイルの取得
- アップロード済みファイルのダウンロード

**主要な出力内容**：
1. 指定されたバイナリファイルのHTTPレスポンス
2. Content-Dispositionヘッダーによるファイル名指定
3. MIMEタイプの自動または手動設定
4. attachmentまたはinline表示モードの選択

**帳票の出力タイミング**：ResponseFactory::download()またはResponseFactory::file()メソッドの呼び出し時にBinaryFileResponseが生成され、クライアントへのファイル送信が開始される。

**帳票の利用者**：アプリケーション開発者、エンドユーザー（ファイルダウンロード実行者）

## 帳票種別

バイナリファイルダウンロード / ファイル出力

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | 任意の画面 | 開発者定義 | Response::download()またはResponse::file()呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | 任意（PDF / Excel / 画像 / ZIP等） |
| 用紙サイズ | - |
| 向き | - |
| ファイル名 | $nameパラメータまたは元ファイル名 |
| 出力方法 | HTTPダウンロード（attachment）またはインライン表示（inline） |
| 文字コード | ファイル依存 |

### BinaryFileResponse固有設定

| 項目 | 内容 |
|-----|------|
| Content-Disposition | attachment（ダウンロード）/ inline（表示） |
| autoEtag | デフォルトtrue |
| autoLastModified | デフォルトtrue |
| X-Sendfile対応 | Nginx/Apache X-Sendfile対応 |

## 帳票レイアウト

### レイアウト概要

BinaryFileResponseはバイナリファイルをそのまま送信するため、レイアウト構造はファイル自体に依存する。

```
┌─────────────────────────────────────┐
│          HTTPヘッダー部              │
├─────────────────────────────────────┤
│          ファイルコンテンツ           │
│       （バイナリデータ）              │
│                                     │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Content-Type | ファイルのMIMEタイプ | 自動検出またはheadersパラメータ | application/pdf等 |
| 2 | Content-Disposition | ダウンロード設定 | $dispositionパラメータ | attachment; filename="xxx" |
| 3 | Content-Length | ファイルサイズ | ファイルシステム | バイト数 |
| 4 | Last-Modified | 最終更新日時 | ファイルシステム | RFC 7231形式 |
| 5 | ETag | エンティティタグ | ファイルハッシュ | "xxx" |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | ファイルコンテンツ | バイナリファイル本体 | 指定ファイルパス | バイナリ | - |

### フッター部

フッター部は特に定義されない。

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| file | ファイルパスまたはSplFileInfoオブジェクト | Yes |
| name | ダウンロード時のファイル名 | No |
| headers | 追加HTTPヘッダー | No |
| disposition | attachment / inline | No（デフォルト: download時attachment、file時inline） |

### ソート順

バイナリファイル出力のため、ソート順は適用されない。

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| - | - | - |

### 改ページ条件

バイナリファイル出力のため、改ページ条件は適用されない。

## データベース参照仕様

### 参照テーブル一覧

BinaryFileResponse自体はデータベースを参照しない。ファイルパスの取得にデータベースを参照する場合は、呼び出し元で処理する。

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| - | - | - |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| fallbackName | str_replace('%', '', Str::ascii($name)) | - | ASCII文字にフォールバック |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[download/file メソッド呼び出し] --> B[BinaryFileResponse生成]
    B --> C{ファイル名指定あり?}
    C -->|Yes| D[Content-Disposition設定]
    C -->|No| E[元ファイル名を使用]
    D --> F[fallbackName生成]
    E --> F
    F --> G[HTTPヘッダー設定]
    G --> H[ファイルストリーミング]
    H --> I[クライアントへ送信]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| ファイル不存在 | 指定パスにファイルがない | FileNotFoundException | ファイルパスを確認 |
| 権限エラー | ファイル読み取り権限なし | UnreadableFileException | パーミッション確認 |
| 無効なファイル | ディレクトリパスを指定 | ExpectedFileException | ファイルパスを指定 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 単一ファイル |
| 目標出力時間 | ファイルサイズ・帯域に依存 |
| 同時出力数上限 | サーバーリソースに依存 |

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

- ファイルパスにユーザー入力を使用する場合は、パストラバーサル攻撃を防ぐためのバリデーションが必要
- 機密ファイルへのアクセス制御（認証・認可）を適切に実装すること
- Content-Dispositionのファイル名にはサニタイズが必要
- X-Sendfile使用時は、Webサーバーの設定でアクセス可能ディレクトリを制限すること

## 備考

- Symfony\Component\HttpFoundation\BinaryFileResponseを使用している
- download()メソッドはdispositionがattachment、file()メソッドはinline（ブラウザ内表示）がデフォルト
- fallbackName()メソッドにより、非ASCII文字を含むファイル名もサポート

---

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

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

### 推奨読解順序

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

BinaryFileResponseはSymfony HttpFoundationコンポーネントのクラスを使用しているため、Symfonyの実装を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | BinaryFileResponse.php | `vendor/symfony/http-foundation/BinaryFileResponse.php` | BinaryFileResponseの基本実装を理解する |

**読解のコツ**: Symfonyのコンポーネントとして提供されており、X-Sendfile対応やRange Request対応が含まれている。

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

処理の起点となるResponseFactoryのdownload()とfile()メソッドを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ResponseFactory.php | `src/Illuminate/Routing/ResponseFactory.php` | download()とfile()メソッドの実装を確認 |

**主要処理フロー**:
1. **行263-281**: download()メソッドの実装
2. **行274**: BinaryFileResponseインスタンス生成
3. **行276-278**: ファイル名が指定されている場合のContent-Disposition設定
4. **行289-304**: file()メソッドの実装（inline表示用）
5. **行289-292**: fallbackName()メソッドによる非ASCII文字のサニタイズ

#### Step 3: コントラクトインターフェースを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ResponseFactory.php | `src/Illuminate/Contracts/Routing/ResponseFactory.php` | download()とfile()メソッドのインターフェース定義 |

**主要処理フロー**:
- **行92-101**: download()メソッドのインターフェース定義
- **行103-110**: file()メソッドのインターフェース定義

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

```
ResponseFactory::download() / ::file()
    │
    ├─ new BinaryFileResponse($file, 200, $headers, true, $disposition)
    │
    ├─ setContentDisposition()
    │      └─ fallbackName()
    │             └─ Str::ascii($name)
    │
    └─ BinaryFileResponse
           ├─ prepare() - HTTPヘッダー設定
           ├─ setAutoEtag() - ETag自動生成
           └─ setAutoLastModified() - 更新日時自動設定
```

### データフロー図

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

ファイルパス    ───▶ ResponseFactory     ───▶ HTTPレスポンス
$file                ::download()             (BinaryFileResponse)
                     ::file()
                          │
                          ▼
                   BinaryFileResponse
                          │
                          ▼
                   ファイルストリーミング
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ResponseFactory.php | `src/Illuminate/Routing/ResponseFactory.php` | ソース | download()/file()メソッドの実装 |
| ResponseFactory.php | `src/Illuminate/Contracts/Routing/ResponseFactory.php` | ソース | インターフェース定義 |
| Response.php | `src/Illuminate/Support/Facades/Response.php` | ソース | Facadeクラス |
| BinaryFileResponse.php | `vendor/symfony/http-foundation/BinaryFileResponse.php` | ソース | Symfony基底クラス |
| Str.php | `src/Illuminate/Support/Str.php` | ソース | fallbackName()で使用するascii()メソッド |
