115 lines
4.3 KiB
Markdown
115 lines
4.3 KiB
Markdown
[](https://github.com/blax-software)
|
|
|
|
# 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](https://github.com/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
|
|
|
|
```bash
|
|
composer require blax-software/laravel-files
|
|
```
|
|
|
|
Publish the config and migrations:
|
|
|
|
```bash
|
|
php artisan vendor:publish --tag=files-config
|
|
php artisan vendor:publish --tag=files-migrations
|
|
php artisan migrate
|
|
```
|
|
|
|
Add the trait to any model:
|
|
|
|
```php
|
|
use Blax\Files\Traits\HasFiles;
|
|
|
|
class User extends Model
|
|
{
|
|
use HasFiles;
|
|
}
|
|
```
|
|
|
|
Attach a file:
|
|
|
|
```php
|
|
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](docs/installation.md) | Requirements, installation, configuration |
|
|
| [Attaching Files](docs/attaching-files.md) | The `HasFiles` trait, roles, attach/detach, reordering |
|
|
| [File Operations](docs/file-operations.md) | Creating files, reading/writing contents, duplication, scopes |
|
|
| [Uploading](docs/uploading.md) | Single uploads, chunked uploads, progress events |
|
|
| [Serving Files](docs/serving-files.md) | The Warehouse, inline responses, downloads |
|
|
| [Image Optimization](docs/image-optimization.md) | On-the-fly resizing, WebP, quality control |
|
|
| [Configuration](docs/configuration.md) | Full reference for `config/files.php` |
|
|
| [Artisan Commands](docs/artisan-commands.md) | `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
|
|
|
|
```bash
|
|
composer test
|
|
# or
|
|
./vendor/bin/phpunit
|
|
```
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE) for details.
|
|
|
|
---
|
|
|
|
## Star History
|
|
|
|
<a href="https://www.star-history.com/?repos=blax-software%2Flaravel-files&type=date&legend=top-left">
|
|
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=blax-software/laravel-files&type=date&theme=dark&legend=top-left" />
|
|
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=blax-software/laravel-files&type=date&legend=top-left" />
|
|
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=blax-software/laravel-files&type=date&legend=top-left" />
|
|
</picture>
|
|
</a>
|