Implementing Secure Livewire File Uploads with Validation and Recovery

The Problem: Handling File Uploads without Page Refreshes

Implementing file uploads in a reactive framework can lead to two common failure points: users uploading oversized or malicious files that crash the server, and storage failures that force users to re-select their files from the local disk. The goal is to create a seamless upload flow that validates files in real-time and recovers gracefully from filesystem errors.

Prerequisites

• Laravel 8+ with Livewire 2.x installed.
• PHP fileinfo extension enabled for MIME type validation.
• A configured filesystem disk (e.g., the public disk pointing to storage/app/public) with write permissions for the web server user.
• A route rendering the component, such as Route::get('/upload', UploadPhoto::class);.

Implementation Procedure

1. Configure the Component Class

The component must use the WithFileUploads trait to handle the temporary upload process that Livewire manages behind the scenes.

namespace App\Http\Livewire;

use Livewire\Component;
use Livewire\WithFileUploads;
use Illuminate\Support\Facades\Log;

class UploadPhoto extends Component
{
    use WithFileUploads;

    public $photo;

    protected $rules = [
        'photo' => 'image|max:2048', // Limit to 2MB
    ];

    public function upload()
    {
        $this->validate();

        try {
            // Store the file on the 'public' disk in the 'photos' directory
            $path = $this->photo->store('photos', 'public');

            // Reset property to clear the form
            $this->photo = null;
            
            session()->flash('message', 'Photo uploaded successfully.');
        } catch (\Exception $e) {
            // Log the error and notify the user without clearing the file input
            Log::error('Livewire storage failure: ' . $e->getMessage());
            $this->addError('photo', 'The server could not save the file. Please try again.');
        }
    }

    public function render()
    {
        return view('livewire.upload-photo');
    }
}

2. Create the Reactive Blade View

Bind the file input using wire:model. This allows Livewire to upload the file to a temporary directory as soon as it is selected, before the final submit button is pressed.

<div>
    @if (session()->has('message'))
        <div class="alert alert-success">{{ session('message') }}</div>
    @endif

    <form wire:submit.prevent="upload">
        <div>
            <label>Upload Photo (Max 2MB):</label>
            <input type="file" wire:model="photo" accept="image/*">
            @error('photo') <span class="error">{{ $message }}</span> @enderror
        </div>

        <button type="submit">Save Photo</button>
    </form>
</div>

3. Link Storage for Public Access

To make the stored files accessible via a URL, create the symbolic link from the storage folder to the public directory:

# Run this in the project root
php artisan storage:link

Verification and Diagnostic Checks

Scenario	Expected Result	Verification Method
Valid Image (<2MB)	Success message; file stored.	Check storage/app/public/photos for the file.
Invalid Type (e.g. .pdf)	Validation error displayed.	Confirm no file is written to the photos directory.
Storage Failure	Custom error message; file retained.	Temporarily run chmod -w storage/app/public and attempt upload.

Recovery and Rollback

Because $this->photo->store() is the only state-changing operation, recovery is handled via the try-catch block. If the operation fails, the $photo property is not reset to null. This ensures the file remains in the temporary storage and the user does not have to re-upload the file from their computer to retry the operation.

Limitations

• Temporary File Lifespan: Livewire temporary files are deleted automatically after the request cycle or by a scheduled cleanup task. Never store the temporary path in a database; always use store() to move it to permanent storage.
• Remote Disk Permissions: When using S3 or other cloud disks, a failure in store() may occur if the IAM policy lacks s3:PutObject permissions. This will trigger the catch block rather than a validation error.