Vue.js と Vite を使った Laravel のファイルアップロード
認証付きの Laravel アプリに Vue.js のファイル選択機能を追加し、転送完了と保存確認を混同せずにアップロードの進捗を表示します。エンドポイントは JPEG、PNG、PDF ファイルを非公開の隔離領域に受け入れ、受領情報を返します。ファイルの受領と、ダウンロードの承認は別の処理です。
前提条件
- セッションログインが動作し、
usersテーブルと Blade ページを備えた既存の Laravel 13 アプリケーション - Laravel が必要とする拡張機能、Fileinfo、使用するデータベース用の PDO ドライバーを備えた PHP
- Composer、Node.js 24.22.2、Corepack 0.34.5、および Corepack で選択した Yarn 4.12.0
- ページと JSON アップロードエンドポイントに対する同一オリジンの HTTPS
2026年11月7日の再現環境では、Laravel 13.32.0、PHP 8.4.27、Composer 2.11.1、Node.js 24.22.2、Corepack 0.34.5、Yarn 4.12.0、Vue 3.5.42 を使用しています。これらはテスト済みのバージョンであり、Laravel の最小要件ではありません。以前の再現環境では Node.js 24.21.0 を使用していました。
Node.js 24 を継続して使用するアプリケーションには、24.22.2 またはそれ以降のメンテナンス対象の 24.x パッチをインストールしてください。10月のセキュリティリリースでは、24.22.1 に修正が含まれています。ただし、この勧告だけでは、このアップロード連携が悪用可能だったとは判断できません。Node.js 24 は引き続きサポート対象の LTS 系列です。より新しい LTS 系列は Node.js 26 です。この手順は既存の Node.js 24 アプリケーションを対象としています。メジャーバージョンを変更する前に、連携全体を再テストしてください。
既存の PHP 8.4 アプリケーションでは、8.4.27 以降のメンテナンス対象の 8.4 パッチ、または同等のセキュリティ修正を含むベンダービルドを使用してください。PHP の10月21日の勧告は、8.4.27 で修正された重大な脆弱性を二つ扱っています。未修正の 8.4.26 でこの構成を再現しないでください。依存関係を更新する際は、連携を再テストしてください。
PHP の別の10月23日のセッションに関する勧告は、セッションのアップロード進捗機能が有効で、アプリケーションコードが
session_start() より前に ini_set() を使って
session.serialize_handler を php_binary または php_serialize から php に切り替える場合、8.4.27 にも適用されます。この構成では、リクエストの解析前に php.ini またはサーバー設定で
session.upload_progress.enabled=0 を設定し、すべての PHP ワーカーを再起動してください。実行時にハンドラーを変更しないアプリケーションでは、この機能を有効のままにできます。このコンポーネントは Axios のアップロード進捗を使用するため、PHP のセッションアップロード進捗機能は不要です。
認証の設定は、このアップロード連携の対象外です。Laravel のスターターキットまたは既存のログインを使用し、auth を無条件に固定のユーザー ID に置き換えないでください。Laravel のスターターキットを参照してください。
Laravel プロジェクトの設定
artisan、package.json、およびアプリケーション固有の
yarn.lock があるアプリケーションのルートで、次のコマンドを実行してください。先に package.json で "packageManager": "yarn@4.12.0" を設定してください。フロントエンドのパッケージは順番にインストールしてください。インストールに失敗した場合は、エラーを修正してからブロックを再実行してください。
(
if [ ! -f artisan ] || [ ! -f package.json ] || [ ! -f yarn.lock ]; then
printf 'Use the Laravel application root with its own Yarn lockfile.\n' >&2
exit 1
fi
for reader_tool in node corepack; do
if ! command -v "$reader_tool" >/dev/null 2>&1; then
printf 'Install the prerequisite: %s\n' "$reader_tool" >&2
exit 1
fi
done
corepack yarn add --exact vue@3.5.42 axios@1.13.6 &&
corepack yarn add --dev --exact @vue/compiler-sfc@3.5.42 @vitejs/plugin-vue@6.0.9 vite@8.3.0 laravel-vite-plugin@3.2.0
)
既存の Laravel Vite 入力リストに resources/js/upload.ts を追加し、プラグインに vue() がなければ追加してください。特にログインに Inertia スターターキットを使用している場合は、ほかのエントリー、プラグイン、エイリアスを維持してください。最小構成の Blade アプリケーションでは、vite.config.ts は次のようになります。
import vue from '@vitejs/plugin-vue'
import laravel from 'laravel-vite-plugin'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [laravel({ input: ['resources/js/upload.ts'], refresh: true }), vue()],
})
コントローラーでは、local ディスクがローカルドライバーを使用し、ルートが storage/app/private に設定されている必要があります。config/filesystems.php とキャッシュ済みの設定を確認してください。local という名前のディスクでも、カスタマイズされている場合があります。このディレクトリは Web ルートの外に置き、公開 URL やストレージのシンボリックリンクを設けないでください。本番環境ではデバッグ出力を無効にし、アプリケーションプロセスが自身の非公開ストレージに書き込むようにしてください。Laravel のファイルシステム設定を参照してください。
(任意)Quick Admin Panel による CRUD のひな形生成
QuickAdminPanelは、この記事の元の背景に含まれていました。生成された管理リソースを使用する場合は、既存のセッションログインとポリシーにこれらのルートを組み込んでください。この Laravel 13 の例を使用する前に、生成されたアプリケーションの Laravel バージョンを確認してください。プロバイダー、ミドルウェア、認可ルールを丸ごと上書きしないでください。
安全なアップロード API の実装
この JSON エンドポイントでは、ページの Cookie セッションと CSRF 保護を共有するため、意図的に routes/web.php を使用します。URL が /api/ で始まっていても、ルートが自動的にステートレスになるわけではありません。新規の Laravel アプリケーションには、API ルーティングをインストールするまで
routes/api.php がありません。SPA と API を別々にデプロイする必要がある場合は、php artisan install:api と
Sanctum のステートフル SPA 設定に従ってください。それ以外はステートレスな API ルートに CSRF ヘッダーを追加するだけでは不十分です。Laravel のルーティングと
Sanctum の SPA 認証を参照してください。
専用リクエストクラスの追加
app/Http/Requests/FileUploadRequest.php を作成してください。MIME 検証では内容を調べます。ブラウザーの accept 属性とクライアント側の MIME チェックは、選択の補助にすぎません。この検証でも、ファイルを安全に表示または実行できるとは判断できません。
<?php
namespace App\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
class FileUploadRequest extends FormRequest
{
public function authorize(): bool
{
return $this->user() !== null;
}
public function rules(): array
{
return [
'file' => ['required', 'file', 'min:1', 'max:10240', 'mimes:jpeg,png,pdf'],
];
}
}
リクエストクラスを使用するようにコントローラーを更新
app/Http/Controllers/API/FileUploadController.php を作成してください。生成した受領 ID と認証済みユーザー ID で保存パスを決定します。アップロードされたファイル名でディレクトリや接尾辞を決定することはありません。一時ファイルと完了済みファイルは同じローカルファイルシステムを使用するため、サーバーが成功を返す前に名前変更が完了します。後続のレビュータスクでは、完了済みの受領ファイル名だけを処理対象にしてください。
<?php
namespace App\Http\Controllers\API;
use App\Http\Controllers\Controller;
use App\Http\Requests\FileUploadRequest;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Str;
use RuntimeException;
use Throwable;
class FileUploadController extends Controller
{
public function upload(FileUploadRequest $request): JsonResponse
{
$id = (string) Str::uuid();
$directory = 'quarantine/'.$request->user()->getAuthIdentifier();
$temporary = $directory.'/'.$id.'.part';
$destination = $directory.'/'.$id;
$disk = Storage::disk('local');
try {
$stored = $request->file('file')->storeAs($directory, $id.'.part', 'local');
if ($stored === false || !$disk->move($temporary, $destination)) {
throw new RuntimeException('Private storage failed');
}
} catch (Throwable) {
// Log only the generated receipt, never a path, request body or exception trace.
Log::error('Private upload failed', ['receipt' => $id]);
try {
$disk->delete($temporary);
} catch (Throwable) {
Log::warning('Private upload cleanup failed', ['receipt' => $id]);
}
return response()->json(['message' => 'Upload could not be stored.'], 500);
}
return response()->json(['id' => $id, 'message' => 'File received for review.'], 201);
}
}
この例は、ローカルディスクの名前変更の動作に依存しています。オブジェクトストレージのドライバーには、ステージングと公開に関する独自の取り決めが必要です。デプロイ前に、放置された .part ファイルの削除をスケジュールし、ユーザーごとの保持制限とストレージ割り当てを設けてください。認可を伴う別個のレビューおよびダウンロードフローを実装するまで、ファイルは非公開のままです。この例には公開ダウンロードルートはありません。
ルートの保護
ほかのアプリケーションルートを残したまま、routes/web.php に次のルートを追加してください。
<?php
use App\Http\Controllers\API\FileUploadController;
use Illuminate\Support\Facades\Route;
Route::middleware('auth')->group(function () {
Route::view('/uploads', 'uploads');
Route::post('/api/upload', [FileUploadController::class, 'upload'])
->middleware('throttle:uploads');
});
リミッターは、未登録の RouteServiceProvider ではなく、既存の AppServiceProvider::boot に登録してください。以下は最小構成の app/Providers/AppServiceProvider.php 全体です。既存のプロバイダーがほかの役割も担っている場合は、そこにリミッターを組み込んでください。
<?php
namespace App\Providers;
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
public function boot(): void
{
RateLimiter::for('uploads', function (Request $request) {
return Limit::perMinute(10)->by((string) $request->user()->getAuthIdentifier());
});
}
}
標準のアプリケーションひな形と同様に、bootstrap/providers.php 内の
AppServiceProvider を維持してください。web グループのデフォルトのリクエスト偽造保護を有効にしたまま、このエンドポイントを除外しないでください。Laravel 13 では、ブラウザーからの安全な同一オリジンの証拠があれば、トークン検証前に通過する場合があります。それ以外のリクエストでは、セッショントークンの確認にフォールバックします。ページは、このフォールバック用にトークンを送信します。Laravel のリクエスト偽造保護を参照してください。
Vue コンポーネントの作成
アプリケーションの既存のエントリーポイントはそのままに、resources/js/upload.ts を作成してください。レンダー関数をマウントすることで、Blade に埋め込んだカスタム要素が
Vue のランタイムテンプレートコンパイラーに依存するのを避けられます。
import { createApp } from 'vue'
import FileUpload from './components/FileUpload.vue'
createApp(FileUpload).mount('#app')
resources/js/components/FileUpload.vue を作成してください。multipart の境界は Axios が構築します。進捗は、201 レスポンスで保存が確認されるまで 100 未満にとどまります。60秒のタイムアウトには転送とレスポンス待ちの両方が含まれるため、低速な接続では 10 MiB 未満のファイルでもタイムアウトする場合があります。キャンセルやタイムアウトが発生しても、サーバーへの書き込みはロールバックされません。自動再試行は行いません。リクエストごとに新しい受領情報が割り当てられるため、未確認のアップロードを再送する前に、サーバーの隔離領域を確認してください。
<script setup>
import axios from 'axios'
import { onBeforeUnmount, ref } from 'vue'
const file = ref(null)
const fileInput = ref(null)
const progress = ref(0)
const message = ref('')
const uploading = ref(false)
let controller = null
function selectFile(event) {
const selected = event.target.files?.[0]
file.value = null
progress.value = 0
if (!selected) return
if (
selected.size < 1024 ||
selected.size > 10 * 1024 * 1024 ||
!['image/jpeg', 'image/png', 'application/pdf'].includes(selected.type)
) {
message.value = 'Choose a JPEG, PNG or PDF between 1 KiB and 10 MiB.'
return
}
file.value = selected
message.value = 'Ready to upload.'
}
async function uploadFile() {
if (!file.value || uploading.value) return
const csrf = document.querySelector('meta[name="csrf-token"]')?.getAttribute('content')
if (!csrf) {
message.value = 'Reload this page before uploading.'
return
}
uploading.value = true
controller = new AbortController()
progress.value = 0
message.value = 'Uploading…'
const body = new FormData()
body.append('file', file.value)
try {
const response = await axios.post('/api/upload', body, {
headers: { Accept: 'application/json', 'X-CSRF-TOKEN': csrf },
signal: controller.signal,
timeout: 60_000,
onUploadProgress(event) {
if (event.total)
progress.value = Math.min(99, Math.floor((100 * event.loaded) / event.total))
},
})
if (response.status !== 201 || typeof response.data.id !== 'string' || !response.data.id) {
throw new Error('Invalid receipt')
}
progress.value = 100
message.value = 'File received for review.'
file.value = null
if (fileInput.value) fileInput.value.value = ''
} catch (error) {
const status = axios.isAxiosError(error) ? error.response?.status : undefined
message.value =
status === 422
? 'The server rejected this file. Check its size and type.'
: status === 401 || status === 419
? 'Your session expired. Sign in and reload this page.'
: status === 429
? 'Too many uploads. Wait before trying again.'
: 'Upload not confirmed. It may have reached the server; check before sending it again.'
} finally {
controller = null
uploading.value = false
}
}
function cancel() {
controller?.abort()
}
onBeforeUnmount(cancel)
</script>
<template>
<section aria-label="File upload">
<label>
File
<input
ref="fileInput"
type="file"
accept="image/jpeg,image/png,application/pdf"
:disabled="uploading"
@change="selectFile"
/>
</label>
<button :disabled="!file || uploading" @click="uploadFile">Upload file</button>
<button :disabled="!uploading" @click="cancel">Cancel</button>
<progress aria-label="Upload progress" max="100" :value="progress"></progress>
<p role="status">{{ message }}</p>
</section>
</template>
Blade でのコンポーネントの表示
resources/views/uploads.blade.php を作成してください。
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="csrf-token" content="{{ csrf_token() }}" />
<title>File upload</title>
@vite('resources/js/upload.ts')
</head>
<body>
<h1>Upload a file for review</h1>
<div id="app"></div>
</body>
</html>
ファイルを保存したら、アセットをビルドしてください。
corepack yarn vite build
ログインし、アプリケーションの HTTPS オリジンで /uploads にアクセスしてください。1 KiB から 10 MiB の JPEG、PNG、PDF のいずれかを選び、Upload file を選択してください。ページには、サーバーが保存を確認するまで Uploading… が表示され、確認後は File received for review. が表示されます。その時点で進捗が 100 になります。JSON レスポンスの id は storage/app/private/quarantine/{authenticated-user-id}/{id} を示します。そのファイルのバイト列を入力ファイルと比較し、対応する .part ファイルが残っていないことを確認してください。
大容量ファイルのベストプラクティス
アプリケーションの上限は 10 MiB に維持してください。multipart のオーバーヘッドを考慮して、PHP の upload_max_filesize を 10M に、post_max_size を 12M に設定し、リバースプロキシのリクエストボディ上限を 12 MiB に設定してください。デプロイ環境に合わせて、接続とボディのタイムアウト、および PHP の実行時間に上限を設けてください。Laravel の実行前にプロキシが大きなリクエストを拒否する場合があります。コンポーネントは、その場合も未確認のアップロードとして扱います。
さらに大きな転送には、tus などの再開可能なプロトコルを、対応する受信サーバーと組み合わせて使用してください。内容のレビュー、マルウェアスキャン、認可付きダウンロードは別個の作業です。隔離されたファイルをユーザーが利用できるようにする前に、これらを完了する必要があります。
アップロードフローのテスト
認証付きアプリケーションに tests/Feature/FileUploadTest.php を作成してください。これらのテストは、Laravel の非公開ストレージのフェイクを使い、実際のルート、リクエストバリデーター、コントローラーを通して実行します。
<?php
namespace Tests\Feature;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Storage;
use Tests\TestCase;
class FileUploadTest extends TestCase
{
use RefreshDatabase;
public function test_private_upload_is_owned_and_complete(): void
{
Storage::fake('local');
$user = User::factory()->create();
$bytes = "%PDF-1.7\n".str_repeat('reader upload ', 160)."\n%%EOF\n";
$file = UploadedFile::fake()->createWithContent('review.pdf', $bytes);
$response = $this->actingAs($user)->postJson('/api/upload', ['file' => $file]);
$response->assertCreated()->assertJson(['message' => 'File received for review.']);
$path = 'quarantine/'.$user->id.'/'.$response->json('id');
Storage::disk('local')->assertExists($path);
$this->assertSame($bytes, Storage::disk('local')->get($path));
Storage::disk('local')->assertMissing($path.'.part');
$this->assertCount(1, Storage::disk('local')->allFiles());
}
public function test_anonymous_upload_is_rejected(): void
{
$this->postJson('/api/upload')->assertUnauthorized();
}
public function test_invalid_and_oversized_files_are_rejected(): void
{
Storage::fake('local');
$this->actingAs(User::factory()->create());
$this->postJson('/api/upload')->assertUnprocessable();
$this->postJson('/api/upload', [
'file' => UploadedFile::fake()->create('large.pdf', 10241, 'application/pdf'),
])->assertUnprocessable();
$this->postJson('/api/upload', [
'file' => UploadedFile::fake()->create('script.txt', 2, 'text/plain'),
])->assertUnprocessable();
$this->assertSame([], Storage::disk('local')->allFiles());
}
public function test_upload_rate_limit_is_enforced(): void
{
$this->actingAs(User::factory()->create());
for ($attempt = 0; $attempt < 10; $attempt++) {
$this->postJson('/api/upload')->assertUnprocessable();
}
$this->postJson('/api/upload')->assertTooManyRequests();
}
}
機能テストを実行してください。
php artisan test --filter=FileUploadTest
これらのストレージフェイクを使うテストでは、稼働中のアプリケーションでのリクエスト偽造保護は確認できません。Laravel は機能テストでそのミドルウェアをバイパスします。実行中のアプリケーションで、トークンのない認証済みクロスオリジンリクエストを確認し、419 が返ることを確かめてください。Sec-Fetch-Site がない場合のトークンフォールバックも確認してください。トークンがない場合や誤っている場合は 419 が返り、有効なセッショントークンがある場合はバリデーションに進むはずです。Laravel 13 のデフォルトポリシーでは、安全な同一オリジンのブラウザーリクエストは、トークンなしでも通過する場合があります。
ストレージ障害、リクエスト制限、セッションの有効期限切れ、ページを開いたままのログアウトをテストしてください。アップロード中に Cancel を選択し、結果が未確認と報告されることを確かめてください。サーバーが完了済みファイルを削除したとは想定しないでください。最終レスポンスを遅延または破棄して、同じ境界を確認してください。バイトの転送だけで成功メッセージが表示されてはなりません。ダウンロードルートを追加する際は、あるユーザーが別のユーザーの隔離ファイルを取得できないことをテストしてください。
まとめ
受領したファイルを公開する前に、保持、レビュー、ダウンロードのポリシーを追加してください。マネージドな取り込みと処理については、Transloadit の 🤖 /upload/handle Robotを参照してください。
