Laravelのファイルアップロード実装ガイド｜バリデーション・Storage・S3対応
カテゴリ：Laravel・PHP
Laravel はファイルアップロードに関連する機能が充実しており、バリデーション・ストレージ抽象化・S3連携まで一貫した API で実装できます。本記事では Request::file() の使い方から始まり、バリデーションルール・Storage ファサードによる保存・S3ドライバーの設定まで、実務レベルのファイルアップロード実装を体系的に解説します。
Request::file() と hasFile() の使い方
Laravel のコントローラーでアップロードされたファイルを受け取るには、$request->file() メソッドを使います。このメソッドは Illuminate\Http\UploadedFile インスタンス（Symfony の UploadedFile を継承）を返します。
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Storage;
class FileUploadController extends Controller
{
public function store(Request $request)
{
// ファイルが送信されているか確認
if (!$request->hasFile('avatar')) {
return response()->json(['error' => 'ファイルが選択されていません。'], 422);
}
// UploadedFile インスタンスを取得
$file = $request->file('avatar');
// アップロードが成功しているか確認
if (!$file->isValid()) {
return response()->json(['error' => 'ファイルのアップロードに失敗しました。'], 422);
}
// ファイル情報の取得
$originalName = $file->getClientOriginalName(); // 元のファイル名
$extension = $file->getClientOriginalExtension(); // 元の拡張子
$mimeType = $file->getMimeType(); // サーバー側で判定したMIMEタイプ
$clientMime = $file->getClientMimeType(); // クライアントが申告したMIMEタイプ（信頼しない）
$size = $file->getSize(); // バイト単位のサイズ
$tmpPath = $file->getRealPath(); // 一時ファイルのパス
// 複数ファイルの場合（input[type="file" multiple]）
$files = $request->file('documents');
foreach ($files as $uploadedFile) {
// 各ファイルを処理
}
}
}$request->validate() によるファイルバリデーション
Laravel のバリデーション機能を使うと、ファイルのMIMEタイプ・サイズ・画像の寸法などを宣言的に検証できます。バリデーション失敗時は自動的に 422 レスポンスが返されます。
public function store(Request $request)
{
$validated = $request->validate([
// 基本的なファイルバリデーション
'avatar' => [
'required',
'file', // ファイルであること
'mimes:jpg,jpeg,png,gif,webp', // 許可するMIMEタイプ（拡張子指定でMIMEを自動判定）
'max:5120', // KB単位のサイズ上限（5120KB = 5MB）
],
// 画像専用のバリデーションルール
'thumbnail' => [
'required',
'image', // 画像ファイルであること（JPEG/PNG/GIF/WebP/SVG）
'mimes:jpg,jpeg,png,webp',
'max:2048', // 2MBまで
'dimensions:min_width=100,min_height=100,max_width=4096,max_height=4096',
],
// PDFのバリデーション
'document' => [
'required',
'file',
'mimes:pdf',
'max:20480', // 20MBまで
],
// 複数ファイル
'attachments' => 'required|array|max:5',
'attachments.*' => 'file|mimes:jpg,jpeg,png,pdf|max:10240',
]);
// バリデーション済みファイルを処理
$file = $request->file('avatar');
// ...
}| バリデーションルール | 説明 | 例 |
|---|---|---|
file |
アップロードされたファイルであること | 'file' |
image |
画像ファイル（JPEG/PNG/GIF/WebP/SVG） | 'image' |
mimes |
指定した拡張子のMIMEタイプを許可 | 'mimes:jpg,png,pdf' |
mimetypes |
MIMEタイプを直接指定 | 'mimetypes:image/jpeg,image/png' |
max |
KB単位のサイズ上限 | 'max:10240'（10MB） |
min |
KB単位の最小サイズ | 'min:1'（1KB以上） |
dimensions |
画像の縦横ピクセル数 | 'dimensions:min_width=100' |
Storage::disk()->put() での保存（public / s3 ディスク）
Laravel の Storage ファサードはファイルシステムを抽象化しており、ローカルディスク・public ディスク・S3などのクラウドストレージを同じ API で操作できます。
use Illuminate\Support\Facades\Storage;
public function store(Request $request)
{
$request->validate([
'file' => 'required|file|max:10240',
]);
$file = $request->file('file');
// ===== ローカル保存（storage/app/ 以下）=====
// 自動でユニークなファイル名を生成して保存
$path = $file->store('uploads');
// → storage/app/uploads/xxxx.jpg のような形で保存される
// 第2引数でディスクを指定
$path = $file->store('uploads', 'local');
// ファイル名を指定して保存
$filename = uniqid('file_') . '.' . $file->getClientOriginalExtension();
$path = $file->storeAs('uploads', $filename);
// ===== public ディスク（公開アクセス可能）=====
// storage/app/public/ 以下に保存（公開URL: /storage/... でアクセス可能）
$path = $file->store('avatars', 'public');
// または
$path = Storage::disk('public')->put('avatars', $file);
// 保存パスから公開URLを取得
$url = Storage::disk('public')->url($path);
// → /storage/avatars/xxxx.jpg
// ===== Storage ファサードの各種操作 =====
// ファイルの存在確認
if (Storage::exists('uploads/file.jpg')) { ... }
// ファイルの削除
Storage::delete('uploads/file.jpg');
// ファイルの移動
Storage::move('uploads/temp.jpg', 'uploads/final.jpg');
// ファイルの取得
$contents = Storage::get('uploads/file.txt');
// ファイルのURL取得
$url = Storage::url('uploads/file.jpg');
return response()->json(['path' => $path, 'url' => $url]);
}php artisan storage:link の解説
storage/app/public ディレクトリを Web から公開するには、public/storage というシンボリックリンクを作成する必要があります。このリンクを作成するコマンドが php artisan storage:link です。
# シンボリックリンクを作成
php artisan storage:link
# 出力例:
# The [public/storage] link has been connected to [storage/app/public].
# 作成されたリンクを確認
ls -la public/storage
# lrwxrwxrwx ... public/storage -> /var/www/storage/app/public
# Docker/本番環境での注意点:
# デプロイ時に毎回実行するか、Dockerfile に含める
# RUN php artisan storage:linkシンボリックリンクが作成されると、storage/app/public/avatars/photo.jpg に保存したファイルが https://example.com/storage/avatars/photo.jpg でアクセスできるようになります。
S3ドライバーの設定（.env）
AWS S3 にファイルを保存するには、league/flysystem-aws-s3-v3 パッケージが必要です（Laravel 9以降は標準で含まれる場合あり）。
composer require league/flysystem-aws-s3-v3# .env の設定
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_DEFAULT_REGION=ap-northeast-1
AWS_BUCKET=my-app-bucket
AWS_USE_PATH_STYLE_ENDPOINT=false
# CloudFront 経由でURLを取得したい場合
AWS_URL=https://d1234abcd.cloudfront.net// S3 への保存
$path = $file->store('uploads', 's3');
// S3 への保存（アクセス制御を指定）
$path = Storage::disk('s3')->put('uploads/' . $filename, $file, 'public');
// 署名付きURL（一時的なプライベートファイルへのアクセス）
$url = Storage::disk('s3')->temporaryUrl(
$path,
now()->addMinutes(30) // 30分間有効
);
// S3 のURL取得（バケットが public の場合）
$url = Storage::disk('s3')->url($path);config/filesystems.php の解説
ディスクの設定は config/filesystems.php で管理されています。複数のS3バケットやカスタムディスクを追加することも可能です。
// config/filesystems.php
return [
// デフォルトのファイルシステムディスク
'default' => env('FILESYSTEM_DISK', 'local'),
'disks' => [
'local' => [
'driver' => 'local',
'root' => storage_path('app'),
'throw' => false,
],
'public' => [
'driver' => 'local',
'root' => storage_path('app/public'),
'url' => env('APP_URL') . '/storage',
'visibility' => 'public',
'throw' => false,
],
'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,
],
// カスタムディスク（別のS3バケットなど）
's3-thumbnails' => [
'driver' => 's3',
'key' => env('AWS_ACCESS_KEY_ID'),
'secret' => env('AWS_SECRET_ACCESS_KEY'),
'region' => env('AWS_DEFAULT_REGION'),
'bucket' => env('AWS_THUMBNAILS_BUCKET'),
],
],
// storage:link コマンドで作成するリンクのマッピング
'links' => [
public_path('storage') => storage_path('app/public'),
],
];一時ファイルの扱いとセキュリティ
アップロードされたファイルは一時的に /tmp ディレクトリ等に保存されます。処理後は move_uploaded_file()（PHPの場合）または Laravel の store() 系メソッドで正式な場所に移動され、スクリプト終了時に一時ファイルは自動削除されます。
- Storage の
publicディスクに保存したファイルは Web からアクセスできるため、機密ファイルを置いてはいけない - ファイル名は
hashName()メソッドでランダムなハッシュ名を生成すると安全 - 元のファイル名はデータベースに記録して、実際の保存名とは分離する
- S3 の場合はデフォルトで private のため、公開が必要なファイルは明示的に
publicを指定するか署名付きURLを使う
// セキュアなファイル保存の例
public function store(Request $request)
{
$request->validate([
'document' => 'required|file|mimes:pdf,docx|max:20480',
]);
$file = $request->file('document');
// hashName() でランダムなファイル名を生成（元の拡張子を保持）
$hashedName = $file->hashName(); // 例: 5af75b.pdf
// S3 の private エリアに保存
$path = Storage::disk('s3')->putFileAs(
'documents/' . auth()->id(),
$file,
$hashedName
);
// DBに元のファイル名と保存パスを記録
Document::create([
'user_id' => auth()->id(),
'original_name' => $file->getClientOriginalName(),
'stored_path' => $path,
'mime_type' => $file->getMimeType(),
'size' => $file->getSize(),
]);
return response()->json(['message' => 'アップロード完了']);
}この記事で使えるテストファイル（無料）
- → テスト画像一覧 — バリデーション（mimes/dimensions）のテストに
- → PDFテストファイル一覧 — PDFアップロードのバリデーション検証に
- → 境界値テスト用ファイル一覧 — max バリデーションルールの上限確認に