Laravelファイルダウンロード完全実装｜StreamDownload・S3連携・大容量ファイル対応

Webアプリケーションの開発において、PDF請求書やCSVエクスポート、アップロードされた文書・画像・動画などのファイルダウンロード機能は避けて通れない重要機能です。Laravelには、用途やインフラ構成に合わせて柔軟にファイル配信を行うための仕組み（Storage::download()、response()->download()、response()->streamDownload()、AWS S3署名付きURL）が標準で充実しています。

しかし、実務では「大容量ファイルのダウンロード時にメモリが枯渇する（Allowed memory size exhausted）」「S3上のファイルを安全かつサーバー負荷なくダウンロードさせたい」「パストラバーサル等の脆弱性を防ぎたい」といった高度な課題に直面します。

この記事では、Laravelにおけるファイルダウンロードの基本実装から、response()->streamDownload() によるメモリ枯渇対策、AWS S3連携と署名付き一時URL（Direct Download）の実装、セキュリティ対策や実務Tipsまで、実践的なコードを交えて完全解説します。

複数ファイルをまとめてZip形式で配信したい場合は、Laravel ZipArchiveの使い方：ファイル圧縮と解凍を簡単に実装する方法もあわせて参考にしてください。

1. Storageファサードを使用した基本ダウンロード（Storage::download）

Laravelでファイルを管理する場合、Storageファサード（Flysystemベースのストレージ抽象化）を使用するのが最も標準的で推奨される方法です。ローカルストレージだけでなく、設定変更だけでS3やその他のクラウドストレージにシームレスに切り替えられます。

基本的なダウンロード実装

ストレージディスクに保存されたファイルをダウンロードさせるには、Storage::download()を使用します。

<?php

namespace AppHttpControllers;

use IlluminateHttpRequest;
use IlluminateSupportFacadesStorage;
use SymfonyComponentHttpFoundationStreamedResponse;

class DocumentDownloadController extends Controller
{
    public function download(string $fileName): StreamedResponse
    {
        // 1. ファイルの存在確認
        if (!Storage::disk('local')->exists("documents/{$fileName}")) {
            abort(404, '指定されたファイルが見つかりません。');
        }

        // 2. StreamedResponse を生成して返却
        return Storage::disk('local')->download("documents/{$fileName}");
    }
}

Storage::download()メソッドは、ブラウザがファイルを自動的に保存できるように適切なContent-Disposition: attachmentヘッダーを含むStreamedResponseを生成して返します。

ダウンロードファイル名を指定する（日本語ファイル名対応）

サーバー上に保存されているファイル名（UUIDやタイムスタンプ付きの英数字など）と、ユーザーがダウンロードした際に保存されるファイル名を変更したい場合は、第2引数に任意のファイル名を指定します。

public function downloadInvoice(string $invoiceId): StreamedResponse
{
    $filePath = "invoices/{$invoiceId}.pdf";
    $downloadName = "請求書_{$invoiceId}.pdf";

    return Storage::disk('private')->download($filePath, $downloadName);
}

Laravel内部でRFC 5987（filename*=UTF-8''...）に基づいたエンコーディングが自動的に行われるため、日本語や特殊記号を含むファイル名も文字化けすることなく安全に指定可能です。

カスタムHTTPレスポンスヘッダーの設定

第3引数に連想配列を渡すことで、任意のHTTPレスポンスヘッダーを追加・カスタマイズできます。

public function downloadWithHeaders(string $filePath): StreamedResponse
{
    $headers = [
        'Content-Type' => 'application/pdf',
        'Cache-Control' => 'no-cache, no-store, must-revalidate',
        'Pragma' => 'no-cache',
        'Expires' => '0',
    ];

    return Storage::disk('private')->download($filePath, 'report.pdf', $headers);
}

2. response()->download() によるローカルパス指定ダウンロード

Storageファサードで管理されていないサーバー上の物理絶対パス（例: storage_path()やpublic_path()配下、一時ディレクトリ /tmp 配下など）にあるファイルをダウンロードさせたい場合は、response()->download()を使用します。

<?php

namespace AppHttpControllers;

use SymfonyComponentHttpFoundationBinaryFileResponse;

class TempFileDownloadController extends Controller
{
    public function downloadFromLocalPath(string $fileName): BinaryFileResponse
    {
        $path = storage_path('app/temp/' . basename($fileName));

        if (!file_exists($path)) {
            abort(404, 'ファイルが存在しません。');
        }

        // 引数: 物理ファイルパス, ダウンロード表示名(省略可), レスポンスヘッダー(省略可)
        return response()->download($path, 'exported_report.pdf', [
            'Content-Type' => 'application/pdf',
        ]);
    }
}

ダウンロード完了後に元ファイルを自動削除する（deleteFileAfterSend）

動的に生成した一時PDFやZipファイルなどを、ユーザーへ配信した直後にサーバー上からクリーンアップしたい場合は、deleteFileAfterSend(true)チェーンが非常に便利です。

public function downloadAndCleanup(string $tempZipPath): BinaryFileResponse
{
    // レスポンス送信完了後に一時ファイルを自動削除
    return response()->download($tempZipPath, 'archive.zip')->deleteFileAfterSend(true);
}

3. response()->streamDownload() による大容量ストリーム出力とメモリ枯渇対策

大量のレコード（数万〜数十万行のCSV）や動的に生成する大容量データをダウンロードさせる場合、一度サーバーのメモリ上にすべてのデータを構築してから配信しようとすると、PHPのメモリ制限（Allowed memory size of ... bytes exhausted）に達してシステム障害の原因になります。

Laravelのresponse()->streamDownload()を使用すれば、メモリをほとんど消費せずにデータを1行ずつブラウザへ逐次ストリーミング配信できます。

大量データのCSVストリーミングエクスポート（実践コード）

Eloquentのcursor()（ジェネレータ）とphp://output、PHPのバッファフラッシュを組み合わせた、最も堅牢なCSVエクスポート実装例です。

<?php

namespace AppHttpControllers;

use AppModelsOrder;
use IlluminateHttpRequest;
use SymfonyComponentHttpFoundationStreamedResponse;

class OrderExportController extends Controller
{
    public function exportCsv(Request $request): StreamedResponse
    {
        $fileName = 'orders_' . now()->format('Ymd_His') . '.csv';

        $headers = [
            'Content-Type' => 'text/csv; charset=UTF-8',
            'Content-Disposition' => "attachment; filename="{$fileName}"",
            'Pragma' => 'no-cache',
            'Cache-Control' => 'must-revalidate, post-check=0, pre-check=0',
            'Expires' => '0',
        ];

        $callback = function () use ($request) {
            // 出力ストリームをオープン（直接ブラウザの出力バッファへ書き込み）
            $handle = fopen('php://output', 'w');

            // 1. Excel文字化け防止用 UTF-8 BOM の出力
            fwrite($handle, "");

            // 2. CSVヘッダー行の書き込み
            fputcsv($handle, [
                '注文ID',
                '顧客名',
                '注文金額（円）',
                'ステータス',
                '注文日時',
            ]);

            // 3. cursor() を用いて省メモリでクエリ結果を逐次取得・出力
            $query = Order::query()
                ->with('customer')
                ->when($request->filled('status'), fn ($q) => $q->where('status', $request->status))
                ->orderBy('id');

            $rowCount = 0;

            foreach ($query->cursor() as $order) {
                fputcsv($handle, [
                    $order->id,
                    $order->customer?->name ?? '不明',
                    $order->total_amount,
                    $order->status,
                    $order->created_at->format('Y-m-d H:i:s'),
                ]);

                $rowCount++;

                // 1000行ごとに出力バッファを強制フラッシュしてメモリ蓄積を防止
                if ($rowCount % 1000 === 0) {
                    flush();
                }
            }

            fclose($handle);
        };

        return response()->streamDownload($callback, $fileName, $headers);
    }
}

メモリ枯渇を防ぐ3大テクニック

外部リソース（大容量ストリーム）のパイプ中継

外部ストレージやAPIから取得した大容量ストリームを、Webサーバーのメモリに溜め込まずそのままクライアントへ中継することも可能です。

public function streamExternalResource(): StreamedResponse
{
    $callback = function () {
        // Flysystem から読み込み用ストリームを取得
        $readStream = Storage::disk('s3')->readStream('large-datasets/archive.tar.gz');
        $outputStream = fopen('php://output', 'w');

        // ストリーム同士を直結してメモリ消費ゼロで転送
        stream_copy_to_stream($readStream, $outputStream);

        if (is_resource($readStream)) {
            fclose($readStream);
        }
        fclose($outputStream);
    };

    return response()->streamDownload($callback, 'archive.tar.gz');
}

4. AWS S3連携と署名付きURL（一時URL）による大容量ファイルダウンロード

数百MB〜数GBを超える動画やバックアップファイル、大量の画像を配信する場合、Webサーバー（PHP）を経由してダウンロードさせると、サーバーのネットワーク帯域やCPU、ワーカープロセスが長時間占有されてしまいます。

これを解決する最高効率の手法が、AWS S3の署名付きURL（Pre-signed URL / Temporary URL）を発行し、クライアントからS3へ直接ダウンロード（Direct Download）させる方法です。

1. filesystems.php の S3 設定

まず config/filesystems.php に S3 ディスクを定義し、.env に AWS 認証情報を設定します。

// config/filesystems.php
'disks' => [
    's3' => [
        'driver' => 's3',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION'),
        'bucket' => env('AWS_BUCKET'),
        'url' => env('AWS_URL'),
        'endpoint' => env('AWS_ENDPOINT'),
        'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', false),
        'throw' => false,
    ],
],

2. 署名付き一時URL（temporaryUrl）の発行とリダイレクト

LaravelのStorage::disk('s3')->temporaryUrl()を使えば、指定した有効期限（例: 5分間）だけアクセス可能な安全な署名付きURLを1行で発行できます。

<?php

namespace AppHttpControllers;

use AppModelsVideo;
use IlluminateHttpRedirectResponse;
use IlluminateHttpRequest;
use IlluminateSupportFacadesStorage;

class S3DownloadController extends Controller
{
    public function downloadDirect(Request $request, Video $video): RedirectResponse
    {
        // 1. ユーザーの認可チェック
        $this->authorize('download', $video);

        // 2. ダウンロード時のファイル名とヘッダーを上書き指定
        $downloadFileName = rawurlencode($video->title . '.mp4');

        $temporaryUrl = Storage::disk('s3')->temporaryUrl(
            $video->s3_path,
            now()->addMinutes(5), // 5分間のみ有効
            [
                'ResponseContentDisposition' => "attachment; filename*=UTF-8''{$downloadFileName}",
                'ResponseContentType' => 'video/mp4',
            ]
        );

        // 3. S3の署名付きURLへ直接リダイレクト
        return redirect()->away($temporaryUrl);
    }
}

3. SPA・モバイルアプリ向け API エンドポイントの実装

React / Vue / Next.js やモバイルアプリ等のフロントエンドからダウンロードを行いたい場合は、署名付きURLをJSONレスポンスとして返すAPIを構築します。

use IlluminateHttpJsonResponse;

public function getPresignedUrl(Request $request, int $fileId): JsonResponse
{
    $file = $request->user()->files()->findOrFail($fileId);

    $url = Storage::disk('s3')->temporaryUrl(
        $file->path,
        now()->addMinutes(10),
        [
            'ResponseContentDisposition' => 'attachment; filename="' . $file->original_name . '"',
        ]
    );

    return response()->json([
        'download_url' => $url,
        'expires_in_seconds' => 600,
    ]);
}

5. ファイルダウンロード実装で必須のセキュリティ対策

ユーザーからのリクエストパラメータ（ファイル名やパス）を受け取ってファイルを配信する場合、適切なバリデーションを怠るとサーバー全体の乗っ取りや個人情報漏洩などの重大な脆弱性に直結します。

1. パストラバーサル（ディレクトリトラバーサル）の徹底防御

攻撃者が ../../.env や ../../etc/passwd といった相対パスを指定してサーバー内の非公開ファイルを不正取得する攻撃です。以下の3重防御を必ず実装しましょう。

use IlluminateSupportFacadesStorage;
use IlluminateSupportStr;

public function secureDownload(Request $request)
{
    $inputFileName = $request->query('file');

    // 対策1: basename() でディレクトリセパレータ（/ や ）を強制除去
    $safeFileName = basename($inputFileName);

    // 対策2: 正規表現で許可された文字パターンと拡張子のみに制限
    if (!preg_match('/^[a-zA-Z0-9_-]+.(pdf|csv|xlsx|png|jpg)$/i', $safeFileName)) {
        abort(400, '不正なファイル名形式です。');
    }

    // 対策3: 非公開ディスク内に実体が存在するか検証
    if (!Storage::disk('private')->exists("reports/{$safeFileName}")) {
        abort(404, 'ファイルが見つかりません。');
    }

    return Storage::disk('private')->download("reports/{$safeFileName}");
}

abort()関数の詳細な使い方やエラー画面のカスタマイズについては、Laravelのabort関数の使い方｜404/403エラーページを簡単にカスタマイズで詳しく解説しています。

2. 認可（Authorization）によるアクセス制御

ログインユーザーが「他人の請求書や機密ファイル」をダウンロードできないように、Laravel PolicyまたはGateによる所有権チェックを徹底します。

use AppModelsInvoice;
use IlluminateHttpRequest;

public function downloadInvoice(Request $request, Invoice $invoice)
{
    // Policy による認可（一致しない場合は自動で 403 Forbidden）
    $this->authorize('view', $invoice);

    return Storage::disk('private')->download(
        $invoice->file_path,
        "invoice_{$invoice->invoice_number}.pdf"
    );
}

3. 非公開ストレージ（privateディスク）の利用

公開用の public ディスク（Webルート public/storage）はURLさえ分かれば認証なしで誰でもアクセスできてしまいます。機密ファイルや個人情報は必ず storage/app/private などの非公開領域に保存し、Laravelのコントローラーを経由して配信してください。

6. ダウンロード体験（UX）と実務Tips

大容量処理時の非同期バックグラウンド生成（Queue連携）

数百万件のデータ集計や複雑なPDF生成など、処理に30秒以上かかるダウンロードはWebリクエスト内で行うとタイムアウト（504 Gateway Timeout）になります。

実務でのベストプラクティス：

1. ユーザーが「エクスポート」ボタンをクリックしたら、バックグラウンドジョブ（ExportCsvJob）をキューに投入。
2. ジョブ内でCSVを生成してS3の非公開領域へアップロード。
3. 完了時にLaravelの通知機能（Notification）やメール、WebSocket（Laravel Echo / Reverb）でダウンロード用の署名付きURLをユーザーに通知。

ブラウザ上でのインラインプレビュー表示

ファイルをダウンロード保存させるのではなく、PDFや画像をブラウザのタブ内で直接開かせたい場合は、response()->file() または Storage::response() を使用します（Content-Disposition: inline が設定されます）。

// ブラウザ上でPDFをプレビュー表示
public function previewPdf(string $path)
{
    return response()->file(storage_path("app/private/{$path}"));
    // または
    // return Storage::disk('private')->response($path);
}

よくある質問（FAQ）

Q1. Storage::download と response()->download の違いは何ですか？

Storage::download()はLaravelのストレージディスク設定（ローカル、S3、SFTPなど）を経由してファイルを取得・配信します。一方、response()->download()はサーバー上の物理絶対パスを直接指定して配信します。クラウドストレージへの移行や環境差異を柔軟に吸収できるため、基本的にはStorage::download()の利用を推奨します。

Q2. 大容量CSVのストリーム出力中にタイムアウトになる場合の対策は？

set_time_limit(0);でPHPの実行時間制限を延長するか、Webサーバー（Nginxのproxy_read_timeoutやfastcgi_read_timeout）の設定を見直します。さらに根本的な対策として、前述のとおりLaravel Queueを用いた非同期バックグラウンド生成アーキテクチャへの移行が推奨されます。

Q3. AWS S3の署名付きURL（temporaryUrl）を使用する際、バケットを公開（Public）にする必要がありますか？

いいえ、バケットは完全非公開（Block All Public Access: ON）のままで動作します。temporaryUrl()はAWSのIAMアクセスキーとシークレットを用いて一時的な署名トークンをクエリパラメータに付与するため、バケットを一切公開することなく安全に配信できます。

Q4. 日本語ファイル名がダウンロード時に文字化けする原因と対策は？

ブラウザやOSによってファイル名ヘッダーの解釈が異なることが原因です。LaravelのStorage::download()やresponse()->download()は自動でRFC 5987形式にエンコードするため文字化けしませんが、直接ヘッダーを指定する場合はContent-Disposition: attachment; filename*=UTF-8''{rawurlencode($fileName)}形式で指定してください。

Q5. ダウンロードしたCSVがExcelで開いたときに文字化けする対策は？

Microsoft ExcelがUTF-8形式のCSVをShift-JISとして誤認してしまうことが主な原因です。ストリーム出力の先頭でUTF-8のBOM（fwrite($handle, "");）を書き込むことで、Excelでも文字化けせずに直接開くことができます。

まとめ

Laravelにおけるファイルダウンロードの実装は、シンプルなStorage::download()から、大量データに対応するresponse()->streamDownload()、クラウド環境に最適化されたAWS S3署名付きURL（Direct Download）まで、要件に応じた強力な手段が提供されています。

実務では、データ量とサーバー負荷を考慮した最適なダウンロード方式を選択し、パストラバーサル防止や認証・認可の徹底といったセキュリティ対策を必ず組み込みましょう。

Laravelの主要機能やアーキテクチャ全体を体系的に学びたい方は、Laravelの主要機能一覧：効率的なWeb開発を実現する最新ツールと技術もあわせてチェックしてください。