README

A lightweight Laravel package for managing file and image uploads linked to Eloquent models through a polymorphic database table, powered by Intervention Image v4 and PhpSpreadsheet v5.

Tip

💡 Recommended Alternative: Spatie Media Library

For new projects or complex media handling requirements, we strongly recommend considering Spatie Laravel Media Library (spatie/laravel-medialibrary).

Spatie's library is the established community standard for Laravel media management, offering extensive features such as responsive images, multi-file conversions, custom collections, and active ecosystem support.

tupy/filemanager continues to be maintained primarily for legacy and existing applications (such as Vendamee) and lightweight use cases that rely specifically on this morph table structure and built-in spreadsheet export capabilities.

Features

• 📸 Image Processing with Intervention Image 4.3: Native GD and Imagick drivers with support for modern encoding, transformation, scaling, and Data URI decoding.
• 📁 Polymorphic Storage: Associate uploaded files and images with any Eloquent model using the HasFiles trait.
• 🔄 Custom Image Transformation Closures: Hook into the upload pipeline with full access to Intervention\Image\Interfaces\ImageInterface.
• 📊 Spreadsheet Exporting: Built-in Exporter utility powered by phpoffice/phpspreadsheet (v5) to quickly generate XLSX, CSV, and ODS files.
• 🗄️ Storage Flexibility: Fully integrates with Laravel Filesystem disks and visibility levels.

Requirements

• PHP: ^8.3
• Laravel / Illuminate: ^11.0, ^12.0, or ^13.0
• Intervention Image: ^4.3
• PhpSpreadsheet: ^5.0
• PHP Extensions: ext-zip, ext-mbstring, and ext-gd or ext-imagick

Installation

Install the package via Composer:

composer require tupy/filemanager

Publish Configuration and Migrations

Publish the configuration file:

php artisan vendor:publish --tag=file-manager-config

Publish the database migration for the file_manager table:

php artisan vendor:publish --tag=file-manager-migrations

Run the database migrations:

php artisan migrate

Configuration

The published configuration file is located at config/file-manager.php:

return [
    'no_image' => env('FILE_MANAGER_NO_IMAGE', '/images/noImage.png'),
    'no_file' => env('FILE_MANAGER_NO_FILE', '/images/noImage.png'),
    'placeholder' => env('FILE_MANAGER_PLACEHOLDER', 'https://placehold.it/160x160/c98959/ffffff/&text=D'),
    'path_model' => env('FILE_MANAGER_PATH_TO_MODELS', 'App\\Models\\'),
    'disk_default' => env('FILESYSTEM_DRIVER'),

    // Intervention Image 4 Driver: GD (default) or Imagick
    'image_driver' => env('FILE_MANAGER_IMAGE_DRIVER', \Intervention\Image\Drivers\Gd\Driver::class),

    'interval_temporary' => env('FILE_MANAGER_TIME_TEMPORARY', 5),
    'middleware' => ['auth'],
];

To use Imagick instead of GD, add the following to your .env:

FILE_MANAGER_IMAGE_DRIVER="Intervention\Image\Drivers\Imagick\Driver"

Usage

1. Preparing your Model

Add the HasFiles trait to any Eloquent model you want to attach files to:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Tupy\FileManager\Traits\HasFiles;

class User extends Model
{
    use HasFiles;
}

2. Uploading Images

Use ManagerFile::make() followed by imageUpload():

use Tupy\FileManager\ManagerFile;

$user = User::find(1);
$file = $request->file('avatar'); // or a data:image/... URI or file path

$fileRecord = ManagerFile::make($user, $file, [
    'disk' => 'public',
    'path' => 'avatars',
    'type' => 'avatar',
    'caption' => 'User profile picture',
])->imageUpload();

Using Transformation Closures (Intervention Image v4)

You can pass a closure to imageUpload() to manipulate the image before it is stored. The closure receives an Intervention\Image\Interfaces\ImageInterface instance:

use Intervention\Image\Interfaces\ImageInterface;

// Option A: Modify and return ImageInterface (auto-encoded by file extension)
$fileRecord = ManagerFile::make($user, $file, [
    'disk' => 'public',
    'path' => 'avatars',
    'type' => 'avatar',
])->imageUpload(function (ImageInterface $image) {
    return $image->scale(width: 300);
});

// Option B: Custom encode and return EncodedImageInterface
use Intervention\Image\Encoders\JpegEncoder;

$fileRecord = ManagerFile::make($user, $file, [
    'disk' => 'public',
    'path' => 'banners',
    'type' => 'banner',
])->imageUpload(function (ImageInterface $image) {
    return $image->scaleDown(width: 1200)
                 ->encode(new JpegEncoder(quality: 85));
});

3. Uploading Generic Files (PDF, ZIP, Documents)

For documents that do not require image processing:

use Tupy\FileManager\ManagerFile;

$fileRecord = ManagerFile::make($user, $request->file('contract'), [
    'disk' => 'public',
    'path' => 'documents',
    'type' => 'contract',
    'caption' => 'Employment Contract',
])->uploadFile();

4. Accessing Attached Files

Models using HasFiles gain convenient relationships and helper methods:

// Retrieve all files attached to the model
$files = $user->files;

// Retrieve the first file attached to the model
$firstFile = $user->file;

// Retrieve URL of a file filtered by type
$avatarUrl = $user->profile('avatar');

5. Exporting Spreadsheets

Use the built-in Exporter to generate spreadsheets from array data:

use Tupy\FileManager\Exporter;

$data = [
    'Users' => [
        ['Name' => 'Alice', 'Email' => 'alice@example.com'],
        ['Name' => 'Bob', 'Email' => 'bob@example.com'],
    ],
];

// Generate XLSX and get file information
$result = Exporter::make($data, 'users_export', 'Xlsx')->toArrayPath();

// Download response with auto-delete after download
return Exporter::make($data, 'users_export')->toDownload(delete_after_download: true);

Testing

Run the test suite using PHPUnit:

composer test

Or execute directly:

./vendor/bin/phpunit

Changelog & Upgrades

Please see CHANGELOG.md for details on changes and UPGRADE.md for detailed instructions on migrating from 3.x to 4.0.

Contributing

Contributions are welcome! Please review CONTRIBUTING.md for details.

Security

If you discover any security-related issues, please review our Security Policy before opening a public issue.

License

The MIT License (MIT). Please see License File for more information.