{"id":351,"date":"2025-08-27T20:10:29","date_gmt":"2025-08-27T20:10:29","guid":{"rendered":"https:\/\/1v0.net\/blog\/?p=351"},"modified":"2025-08-27T20:10:31","modified_gmt":"2025-08-27T20:10:31","slug":"how-to-build-a-secure-file-upload-api-in-laravel","status":"publish","type":"post","link":"https:\/\/1v0.net\/blog\/how-to-build-a-secure-file-upload-api-in-laravel\/","title":{"rendered":"How to Build a Secure File Upload API in Laravel"},"content":{"rendered":"\n

How to Build a Secure File Upload API in Laravel<\/strong><\/h2>\n\n\n\n

File uploads are a common attack vector. A secure API must validate file size and MIME type, store files outside the public web root, generate safe filenames, optionally virus-scan, and expose only signed URLs for downloads. In this guide you\u2019ll create a hardened upload API using Laravel\u2019s validation, Storage, policies, and (optionally) a queue-powered malware scan.<\/p>\n\n\n\n

<\/div>\n\n\n\n\n

1 – Configure Storage & App Limits<\/strong><\/h2>\n\n\n\n

We\u2019ll store files on the local<\/code> disk (outside public\/<\/code>) and expose them via signed routes. Also ensure PHP upload limits are sane for your use case.<\/p>\n\n\n

php artisan storage:link   # only if you plan to serve some files via 'public' disk<\/span><\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
storage:link<\/code> is not required for the local<\/code> disk. If you later move to the public<\/code> disk (e.g., for images), the symlink lets the web server reach storage\/app\/public<\/code>. For private downloads we\u2019ll stream files via a controller instead of direct access.<\/p>\n\n\n# .env (review these)\nUPLOAD_MAX_FILESIZE=5M\nPOST_MAX_SIZE=6M\nFILESYSTEM_DISK=local\n\n\n
Match UPLOAD_MAX_FILESIZE<\/code> and POST_MAX_SIZE<\/code> to your needs (and your server\u2019s php.ini<\/code>). Using the local<\/code> disk keeps files private by default.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
2 – Migration & Model for Uploaded Files<\/strong><\/h2>\n\n\n\n
We\u2019ll track uploaded files in a table with original name, stored path, size, detected MIME, and an owner. We\u2019ll also keep a SHA-256 hash for deduplication and security audits.<\/p>\n\n\n
\/\/ database\/migrations\/2025_08_27_000000_create_uploads_table.php<\/span>\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Migrations<\/span>\\Migration<\/span>;\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Schema<\/span>\\Blueprint<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Schema<\/span>;\n\nreturn<\/span> new<\/span> class<\/span> extends<\/span> Migration<\/span> <\/span>{\n    public<\/span> function<\/span> up<\/span>()<\/span>: void<\/span> <\/span>{\n        Schema::create('uploads'<\/span>, function<\/span> (Blueprint $table)<\/span> <\/span>{\n            $table->id();\n            $table->foreignId('user_id'<\/span>)->constrained()->cascadeOnDelete();\n            $table->string('original_name'<\/span>);\n            $table->string('disk'<\/span>)->default('local'<\/span>);\n            $table->string('path'<\/span>);                \/\/ e.g. uploads\/2025\/08\/xyz.pdf<\/span>\n            $table->string('mime'<\/span>, 190<\/span>);           \/\/ detected server-side<\/span>\n            $table->unsignedBigInteger('size'<\/span>);    \/\/ bytes<\/span>\n            $table->string('sha256'<\/span>, 64<\/span>)->index(); \/\/ content hash<\/span>\n            $table->boolean('is_safe'<\/span>)->default(true<\/span>); \/\/ set false during scan if suspect<\/span>\n            $table->timestamps();\n        });\n    }\n    public<\/span> function<\/span> down<\/span>()<\/span>: void<\/span> <\/span>{\n        Schema::dropIfExists('uploads'<\/span>);\n    }\n};<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This schema captures essential metadata for each upload. The sha256<\/code> allows duplicate detection and forensic checks. is_safe<\/code> can be toggled by a scanner job to quarantine suspicious files.<\/p>\n\n\n
\/\/ app\/Models\/Upload.php<\/span>\nnamespace<\/span> App<\/span>\\Models<\/span>;\n\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Eloquent<\/span>\\Model<\/span>;\n\nclass<\/span> Upload<\/span> extends<\/span> Model<\/span>\n<\/span>{\n    protected<\/span> $fillable = [\n        'user_id'<\/span>,'original_name'<\/span>,'disk'<\/span>,'path'<\/span>,'mime'<\/span>,'size'<\/span>,'sha256'<\/span>,'is_safe'<\/span>\n    ];\n\n    public<\/span> function<\/span> user<\/span>()<\/span>\n    <\/span>{\n        return<\/span> $this<\/span>->belongsTo(User::class);\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The model is straightforward, linking each upload to its owner. We\u2019ll use this for authorization and listing endpoints later.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
3 – Validation Rules for Secure Uploads<\/strong><\/h2>\n\n\n\n
Validate both size and type. Prefer mimetypes<\/code> for server-side MIME detection and restrict to a small allow-list.<\/p>\n\n\n
\/**\n * Example rules for PDFs and images only (5 MB max).\n *\/<\/span>\n$rules = [\n    'file'<\/span> => [\n        'required'<\/span>,\n        'file'<\/span>,\n        'max:5120'<\/span>, \/\/ KB => 5 MB<\/span>\n        'mimetypes:application\/pdf,image\/jpeg,image\/png'<\/span>\n    ],\n];<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
max<\/code> is in kilobytes. Using mimetypes<\/code> ensures the server-inspected MIME matches your allow-list, which is safer than extension-only checks. Adjust the list to your needs.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
4 – Upload Controller (Store Privately + Hash)<\/strong><\/h2>\n\n\n\n
This controller validates the upload, stores it with a safe path, computes a hash, and records metadata. We\u2019ll protect the route with auth:sanctum<\/code>.<\/p>\n\n\n
\/\/ app\/Http\/Controllers\/UploadApiController.php<\/span>\nnamespace<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>;\n\nuse<\/span> App<\/span>\\Models<\/span>\\Upload<\/span>;\nuse<\/span> Illuminate<\/span>\\Http<\/span>\\Request<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Storage<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Str<\/span>;\n\nclass<\/span> UploadApiController<\/span> extends<\/span> Controller<\/span>\n<\/span>{\n    public<\/span> function<\/span> store<\/span>(Request $request)<\/span>\n    <\/span>{\n        $data = $request->validate([\n            'file'<\/span> => ['required'<\/span>,'file'<\/span>,'max:5120'<\/span>,'mimetypes:application\/pdf,image\/jpeg,image\/png'<\/span>],\n        ]);\n\n        $file = $data['file'<\/span>];\n\n        \/\/ Generate a safe path (no user-supplied filename)<\/span>\n        $folder = 'uploads\/'<\/span>.now()->format('Y\/m'<\/span>);\n        $filename = Str::uuid().'.'<\/span>.$file->guessExtension(); \/\/ guessExtension() based on MIME<\/span>\n        $path = $file->storeAs($folder, $filename, disk: 'local'<\/span>); \/\/ private by default<\/span>\n\n        \/\/ Read contents for hashing (small\/medium files). For very large files, stream hash.<\/span>\n        $sha256 = hash_file('sha256'<\/span>, Storage::disk('local'<\/span>)->path($path));\n\n        $upload = Upload::create([\n            'user_id'<\/span>       => $request->user()->id,\n            'original_name'<\/span> => $file->getClientOriginalName(),\n            'disk'<\/span>          => 'local'<\/span>,\n            'path'<\/span>          => $path,\n            'mime'<\/span>          => $file->getMimeType(),\n            'size'<\/span>          => $file->getSize(),\n            'sha256'<\/span>        => $sha256,\n            'is_safe'<\/span>       => true<\/span>, \/\/ or false until a scanner job verifies<\/span>\n        ]);\n\n        return<\/span> response()->json([\n            'id'<\/span> => $upload->id,\n            'message'<\/span> => 'Uploaded successfully'<\/span>,\n        ], 201<\/span>);\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Files are stored under storage\/app\/uploads\/YYYY\/MM<\/code> with a UUID filename to avoid collisions and path traversal issues. The DB row ties the file to the user and includes a content hash for later integrity checks or deduplication.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
5 – Secure Download via Signed Route<\/strong><\/h2>\n\n\n\n
Serve private files by streaming them from storage only if the signed URL is valid and the user is authorized.<\/p>\n\n\n
\/\/ app\/Http\/Controllers\/DownloadController.php<\/span>\nnamespace<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>;\n\nuse<\/span> App<\/span>\\Models<\/span>\\Upload<\/span>;\nuse<\/span> Illuminate<\/span>\\Http<\/span>\\Request<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Gate<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Storage<\/span>;\n\nclass<\/span> DownloadController<\/span> extends<\/span> Controller<\/span>\n<\/span>{\n    public<\/span> function<\/span> show<\/span>(Request $request, Upload $upload)<\/span>\n    <\/span>{\n        if<\/span> (! $request->hasValidSignature()) {\n            abort(403<\/span>);\n        }\n\n        \/\/ Optional: owner-only access (or replace with a policy)<\/span>\n        if<\/span> ($request->user()?->id !== $upload->user_id) {\n            abort(403<\/span>);\n        }\n\n        if<\/span> (! $upload->is_safe) {\n            abort(423<\/span>, 'File is quarantined.'<\/span>);\n        }\n\n        return<\/span> Storage::disk($upload->disk)->download($upload->path, $upload->original_name);\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
hasValidSignature()<\/code> ensures the URL wasn\u2019t tampered with. We also restrict downloads to the owner and block quarantined files. The Storage download()<\/code> helper streams the file with correct headers.<\/p>\n\n\n
\/\/ Generate a temporary signed URL (e.g., in a controller or resource)<\/span>\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\URL<\/span>;\n\n$signedUrl = URL::temporarySignedRoute(\n    'uploads.show'<\/span>,\n    now()->addMinutes(10<\/span>),\n    ['upload'<\/span> => $upload->id]\n);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
A temporary signed URL expires after 10 minutes, reducing link leakage risks. Return this from an API that lists a user\u2019s files when they request a download.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
6 – Routes (Protected Upload, Signed Download)<\/strong><\/h2>\n\n\n\n
Separate API (token-protected) for uploads from signed web routes for downloads. You can also expose a \u201clist my files\u201d endpoint.<\/p>\n\n\n
\/\/ routes\/api.php<\/span>\nuse<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>\\UploadApiController<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Route<\/span>;\n\nRoute::middleware('auth:sanctum'<\/span>)->group(function<\/span> ()<\/span> <\/span>{\n    Route::post('\/uploads'<\/span>, [UploadApiController::class, 'store'<\/span>])->name('api.uploads.store'<\/span>);\n});<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The upload route is protected by Sanctum. Only authenticated clients can POST files. Add rate limiting via the throttle<\/code> middleware if needed for abuse control.<\/p>\n\n\n
\/\/ routes\/web.php<\/span>\nuse<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>\\DownloadController<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Route<\/span>;\n\nRoute::get('\/uploads\/{upload}'<\/span>, [DownloadController::class, 'show'<\/span>])\n    ->middleware(['signed'<\/span>,'auth'<\/span>])\n    ->name('uploads.show'<\/span>);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The download route requires a valid signature and an authenticated session. If you need token-based downloads instead, put it under routes\/api.php<\/code> with auth:sanctum<\/code> and still use signed URLs.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
7 – Optional: Antivirus Scan with a Queue Job<\/strong><\/h2>\n\n\n\n
For higher security, queue a malware scan (e.g., ClamAV) right after upload and quarantine the file until it\u2019s cleared.<\/p>\n\n\n
\/\/ app\/Jobs\/ScanUpload.php<\/span>\nnamespace<\/span> App<\/span>\\Jobs<\/span>;\n\nuse<\/span> App<\/span>\\Models<\/span>\\Upload<\/span>;\nuse<\/span> Illuminate<\/span>\\Bus<\/span>\\Queueable<\/span>;\nuse<\/span> Illuminate<\/span>\\Contracts<\/span>\\Queue<\/span>\\ShouldQueue<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Storage<\/span>;\n\nclass<\/span> ScanUpload<\/span> implements<\/span> ShouldQueue<\/span>\n<\/span>{\n    use<\/span> Queueable<\/span>;\n\n    public<\/span> function<\/span> __construct<\/span>(public int $uploadId)<\/span> <\/span>{}\n\n    public<\/span> function<\/span> handle<\/span>()<\/span>: void<\/span>\n    <\/span>{\n        $upload = Upload::find($this<\/span>->uploadId);\n        if<\/span> (! $upload) return<\/span>;\n\n        $path = Storage::disk($upload->disk)->path($upload->path);\n\n        \/\/ Pseudocode: replace with actual scanner integration<\/span>\n        \/\/ $clean = ClamAV::scan($path);<\/span>\n        $clean = true<\/span>;\n\n        $upload->update(['is_safe'<\/span> => (bool) $clean]);\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This job loads the file from disk and runs a scan. If flagged, set is_safe<\/code> to false so downloads are blocked. Wire it in after the upload is created: dispatch(new ScanUpload($upload->id));<\/code>.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
8 – UI: Minimal Upload Form with Progress<\/strong><\/h2>\n\n\n\n
Here\u2019s a tiny Blade page that uploads to the API using Axios, shows a progress bar, and prints the result. Paste a Bearer token from your Sanctum login first.<\/p>\n\n\n
<!-- resources\/views\/uploads\/test.blade.php --><\/span>\n@extends('layouts.app')\n\n@section('content')\n<div<\/span> class<\/span>=\"container\"<\/span>><\/span>\n  <h1<\/span>><\/span>Secure Upload Test<\/h1<\/span>><\/span>\n\n  <div<\/span> class<\/span>=\"mb-3\"<\/span>><\/span>\n    <label<\/span> class<\/span>=\"form-label\"<\/span>><\/span>Bearer Token<\/label<\/span>><\/span>\n    <input<\/span> id<\/span>=\"token\"<\/span> type<\/span>=\"text\"<\/span> class<\/span>=\"form-control\"<\/span> placeholder<\/span>=\"Paste your token\"<\/span>><\/span>\n  <\/div<\/span>><\/span>\n\n  <div<\/span> class<\/span>=\"mb-3\"<\/span>><\/span>\n    <input<\/span> id<\/span>=\"file\"<\/span> type<\/span>=\"file\"<\/span> class<\/span>=\"form-control\"<\/span>><\/span>\n  <\/div<\/span>><\/span>\n\n  <div<\/span> class<\/span>=\"progress mb-3\"<\/span> style<\/span>=\"height: 8px;\"<\/span>><\/span>\n    <div<\/span> id<\/span>=\"bar\"<\/span> class<\/span>=\"progress-bar\"<\/span> role<\/span>=\"progressbar\"<\/span> style<\/span>=\"width: 0%;\"<\/span>><\/span><\/div<\/span>><\/span>\n  <\/div<\/span>><\/span>\n\n  <button<\/span> class<\/span>=\"btn btn-theme\"<\/span> onclick<\/span>=\"upload()\"<\/span>><\/span>Upload<\/button<\/span>><\/span>\n\n  <pre<\/span> id<\/span>=\"result\"<\/span> class<\/span>=\"mt-3\"<\/span>><\/span><\/pre<\/span>><\/span>\n<\/div<\/span>><\/span>\n\n<script<\/span> src<\/span>=\"https:\/\/cdn.jsdelivr.net\/npm\/axios\/dist\/axios.min.js\"<\/span>><\/span><\/script<\/span>><\/span>\n<script<\/span>><\/span>\nfunction<\/span> upload<\/span>(<\/span>) <\/span>{\n  const<\/span> token = document<\/span>.getElementById('token'<\/span>).value;\n  const<\/span> file  = document<\/span>.getElementById('file'<\/span>).files[0<\/span>];\n  if<\/span> (!file) { alert('Choose a file'<\/span>); return<\/span>; }\n\n  const<\/span> form = new<\/span> FormData();\n  form.append('file'<\/span>, file);\n\n  axios.post('\/api\/uploads'<\/span>, form, {\n    headers<\/span>: { Authorization<\/span>: `Bearer ${token}<\/span>`<\/span> },\n    onUploadProgress<\/span>: (evt<\/span>) =><\/span> {\n      if<\/span> (evt.total) {\n        const<\/span> percent = Math<\/span>.round((evt.loaded \/ evt.total) * 100<\/span>);\n        document<\/span>.getElementById('bar'<\/span>).style.width = percent + '%'<\/span>;\n      }\n    }\n  }).then(res<\/span> =><\/span> {\n    document<\/span>.getElementById('result'<\/span>).textContent = JSON<\/span>.stringify(res.data,null<\/span>,2<\/span>);\n  }).catch(err<\/span> =><\/span> {\n    const<\/span> msg = err.response ? JSON<\/span>.stringify(err.response.data,null<\/span>,2<\/span>) : err.message;\n    document<\/span>.getElementById('result'<\/span>).textContent = msg;\n  });\n}\n<\/span><\/script<\/span>><\/span>\n@endsection<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
The UI posts the file to \/api\/uploads<\/code> with a Bearer token. The progress bar updates as the browser streams the file. On success you\u2019ll get the upload ID to fetch a signed download link later.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
Wrapping Up<\/h2>\n\n\n\n
You built a secure upload pipeline: strict validation, private storage, hashed contents, owner-based authorization, signed downloads, and an optional antivirus scan with a queue job. This approach prevents unsafe files from being served publicly and gives you full control over who can access which file and for how long.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
What\u2019s Next<\/h2>\n\n\n\n