blax-software/laravel-files

Universal Laravel file management system — upload, optimize, serve, and attach files to any model.

dev-master 2026-04-17 09:03 UTC

Requires

• php: ^8.1
• blax-software/laravel-workkit: *
• illuminate/container: ^9.0|^10.0|^11.0|^12.0|^13.0
• illuminate/contracts: ^9.0|^10.0|^11.0|^12.0|^13.0
• illuminate/database: ^9.0|^10.0|^11.0|^12.0|^13.0
• illuminate/http: ^9.0|^10.0|^11.0|^12.0|^13.0
• illuminate/routing: ^9.0|^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^9.0|^10.0|^11.0|^12.0|^13.0

Requires (Dev)

• laravel/framework: *
• laravel/pint: ^1.22
• orchestra/testbench: ^10.4
• phpunit/phpunit: ^12.2
• spatie/image: ^3.8

Suggests

• blax-software/laravel-roles: For access control on files via roles & permissions.
• blax-software/laravel-websockets: For real-time chunk upload progress via WebSockets.
• spatie/image: Required for automatic image optimization and resizing (^3.8).

MIT

• Fabian Wagner

• media
• image
• upload
• files
• optimization
• laravel
• warehouse
• chunk-upload
• blax

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

Guide	Description
Installation	Requirements, installation, configuration
Attaching Files	The HasFiles trait, roles, attach/detach, reordering
File Operations	Creating files, reading/writing contents, duplication, scopes
Uploading	Single uploads, chunked uploads, progress events
Serving Files	The Warehouse, inline responses, downloads
Image Optimization	On-the-fly resizing, WebP, quality control
Configuration	Full reference for config/files.php
Artisan Commands	files:cleanup and maintenance

Optional Dependencies

Package	Purpose
spatie/image ^3.8	Image optimization and resizing
blax-software/laravel-roles	Access control on the warehouse endpoint
blax-software/laravel-websockets	Real-time chunk upload progress via WebSockets

Testing

composer test
# or
./vendor/bin/phpunit

License

MIT — see LICENSE for details.