About overtrue/laravel-uploader

overtrue/laravel-uploader is a Laravel package for an upload component for laravel.. It currently has 152 GitHub stars and 93.959 downloads on Packagist (latest version 3.4.0). Install it with composer require overtrue/laravel-uploader. Discover more Laravel packages by overtrue or browse all Laravel packages to compare alternatives.

Last updated October 12, 2026

Laravel Uploader

:palm_tree: An upload component for Laravel.

Requirements

PHP ^8.3
Laravel ^13.30

Upgrading from 3.x? Read the 4.0 migration guide, especially the new failed-write exception contract.

Installing

Install package:
```
$ composer require overtrue/laravel-uploader:^4.0
```
Publish the configuration and translations before using the uploader:
```
$ php artisan vendor:publish --provider=Overtrue\\LaravelUploader\\UploadServiceProvider
```
The provider publishes configuration; it does not automatically merge defaults. Review your existing config/uploader.php when upgrading, preserving custom strategies.

Routing

You can register routes in routes/web.php or other routes file:

\LaravelUploader::routes();

// custom
\LaravelUploader::routes([
   'as' => 'files.upload', 
   'middleware' => ['auth'],
   //...
]);

Usage

Custom controller

If you want to handle file upload, you can do it as simple as:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Routing\Controller as BaseController;
use Overtrue\LaravelUploader\StrategyResolver;

class MyUploadController extends BaseController
{
    public function upload(Request $request)
    {
        return StrategyResolver::resolveFromRequest($request, $request->get('strategy', 'default'))->upload();
    }
}

Custom Response

If you want update the response, you can get key information from the return value object and return a new response:

    public function upload(Request $request)
    {
        $response = StrategyResolver::resolveFromRequest($request, $request->get('strategy', 'default'))->upload();
        
        return response()->json([
            'status' => 'success',
            'url' => $response->url,
            'origin_name' => $response->originalName,
            //...
        ]);
    }

You can get all these public properties:

string $size;
string $path;
?string $mime;
string $url;
string $relativeUrl;
string $filename;
string $originalName;
\Illuminate\Http\UploadedFile   $file;
\Overtrue\LaravelUploader\Strategy $strategy;

Failed uploads

A storage write returning false throws League\Flysystem\UnableToWriteFile, even for a disk configured with throw => false. No success response or FileUploaded event is produced. Exceptions already thrown by storage or event listeners continue to propagate. See catch guidance and retry considerations.

URLs and MIME overrides

uploader.base_uri overrides URLs for non-local disks only. Local disks use their own URL configuration.

A custom strategy's mimes list replaces the entire default list. Omit it to inherit defaults, use [] to reject all types, or ['*'] to allow every type. MIME checks use client-provided metadata, not content inspection; apply any additional validation your application needs.

Testing

composer install
composer test
composer check-style
composer audit

CI verifies Laravel 13 with lowest compatible dependencies on PHP 8.3, and highest compatible dependencies on PHP 8.3, 8.4, and 8.5. The lowest dependency set is checked on the minimum PHP runtime: older transitive dependencies can emit deprecations on PHP 8.4/8.5. Deprecations are not suppressed. Tests use temporary local storage and mocked remote disks; they require no cloud-storage credentials.