README

Laravel Files

A universal, plug-and-play file management system for Laravel. Upload, optimize, serve, and attach files to any Eloquent model — with disk-agnostic storage, automatic image optimization, chunked uploads, and a built-in warehouse endpoint.

Features

• Attach files to any model — polymorphic MorphToMany relationship via the HasFiles trait
• Role-based attachments — tag files as avatar, gallery, document, etc. using the FileLinkType enum or custom strings
• Disk-agnostic — works with any Laravel filesystem disk (local, S3, GCS, …)
• Automatic image optimization — on-the-fly resizing and WebP conversion via spatie/image
• Chunked uploads — upload large files in pieces with real-time progress broadcasting
• Warehouse endpoint — a single route that resolves and serves any file by UUID, encrypted ID, or asset path
• UUID primary keys — every file gets a unique, non-sequential identifier
• Artisan cleanup — remove orphaned files that are no longer attached to any model

Quick Start

composer require blax-software/laravel-files

Publish the config and migrations:

php artisan vendor:publish --tag=files-config
php artisan vendor:publish --tag=files-migrations
php artisan migrate

Add the trait to any model:

use Blax\Files\Traits\HasFiles;

class User extends Model
{
    use HasFiles;
}

Attach a file:

use Blax\Files\Enums\FileLinkType;

$user = User::find(1);

// Upload and attach in one call
$file = $user->uploadFile($request->file('avatar'), as: FileLinkType::Avatar, replace: true);

// Get the avatar back
$avatar = $user->getAvatar();
echo $avatar->url;       // → /warehouse/019d8ab8-…
echo $avatar->size_human; // → "2.4 MB"

Documentation

Optional Dependencies

Testing

composer test
# or
./vendor/bin/phpunit

License

MIT — see LICENSE for details.

Star History