Every Laravel project I’ve worked on, whether it’s a client portal, a content management system, or an e-commerce setup, eventually needs one thing: upload image functionality. User avatars, product photos, blog thumbnails, and document attachments all rely on a reliable image upload system. The requirement shows up predictably, yet every time I reach for the documentation, I find myself piecing together bits from half a dozen sources.
Most tutorials cover the happy path. They show you the store() method, they mention enctype="multipart/form-data", and they call it done. But what about the messy parts? What happens when a user uploads a 12MB file and your server chokes? What if the validation rule passes locally but fails on your production VPS because of a misconfigured php.ini? And does your application actually handle filename collisions gracefully, or is it quietly overwriting files?
This guide is the tutorial I wish existed when I first needed to build robust image upload functionality in Laravel. We are going to cover the full picture, from setting up your database schema for image metadata, to building a form with client-side preview, to handling validation edge cases that tutorials skip, to the security considerations that actually matter in production.
TL;DR
- Laravel handles image uploads through its filesystem layer, no extra packages needed for basic uploads
- Store metadata (not just files) in your database: filename, path, MIME type, size, dimensions
- Always validate on the server AND (for UX) on the client, server-side validation is non-negotiable
- The
storage:linkcommand is still essential for serving files from the public web - Production concerns, PHP limits, disk permissions, filename collisions, are where most tutorials fall short
- ServerAvatar’s built-in server management removes the permission and PHP config headaches from your deployment workflow
How Laravel’s File Storage Actually Works
Before we write a single line of code, it helps to understand what actually happens when a file upload reaches a Laravel application. This model will save you hours of debugging later.
When a user submits a multipart form, Laravel wraps the uploaded file in an UploadedFile object. This isn’t just the file data, it carries metadata: original filename, MIME type, file size, temporary path on disk, and more.
Laravel’s official documentation provides a detailed overview of uploaded files, storage disks, and filesystem operations if you want to explore advanced storage features.
Laravel then hands this object to the filesystem layer, which decides where to put the file based on your config/filesystems.php configuration. The two most relevant disks for image uploads are:
-
public – Files land in
storage/app/public. These are accessible directly from the web, but only if you’ve runphp artisan storage:linkto create a symlink frompublic/storagetostorage/app/public. This is the standard path for user-uploaded content you want publicly served. -
local – Files land in
storage/app. These are not web-accessible by default, which makes them suitable for files you want to control access to, think documents behind a paywall, or images served through a signed URL.
For most image upload use cases, profile photos, product images, gallery uploads, you will use public with the storage:link symlink. I will focus on that path in this guide.
Database Design: Storing Image Metadata the Right Way
Here’s a mistake I see constantly: they store the uploaded image path as a plain string column on the user or product table, and call it a day. This works until you need to display the image’s dimensions, filter by file size, or track which uploads are causing storage bloat.
Separate your concerns. Create a dedicated images table and use a polymorphic relationship. This way, any model in your application can have images, a user, a product, a blog post, without cluttering your main tables.
Schema::create('images', function (Blueprint $table) {
$table->id();
$table->morphs('imageable'); <em>// adds imageable_type and imageable_id</em>
$table->string('filename');
$table->string('path');
$table->string('mime_type');
$table->unsignedInteger('size'); <em>// in bytes</em>
$table->unsignedSmallInteger('width')->nullable();
$table->unsignedSmallInteger('height')->nullable();
$table->timestamps();
});
Storing image width and height can be useful for generating responsive images, validating aspect ratios, and creating thumbnails. You can easily retrieve these values during upload using PHP’s getimagesize() function.
The corresponding Eloquent model is straightforward:
class Image extends Model
{
protected $fillable = [
'filename', 'path', 'mime_type', 'size', 'width', 'height'
];
public function imageable()
{
return $this->morphTo();
}
public function url(): string
{
return asset('storage/' . $this->path . '/' . $this->filename);
}
}
What this gives you that a plain string column doesn’t: you can query images by size, filter by dimensions, eager-load them efficiently, and swap storage backends without touching your application code.
Read Full Article: https://serveravatar.com/laravel-image-upload
Top comments (0)