README

⚠️ This package is currently under active development. Breaking changes may occur. Contributions are welcome!

📦 A modular, clean-architecture-based Laravel package to manage file operations — image, video, documents — with support for multiple drivers (local, cloud, Firebase, etc), progressive images, and flexible configuration.

🔧 Features

• 📁 Save and delete files (single or batch)
• 🧠 Auto-detect file type & handle accordingly
• 🧾 Input-agnostic file handling (UploadedFile, base64 data URI, raw SVG string)
• 🌁 Image processing (blurhash, low quality, watermark, optimized AVIF/WebP)
• 🧩 Structured variants (original, optimized, low_quality, watermark)
• ☁️ Extensible storage drivers: local, S3, Firebase, etc.
• ⚙️ Clean architecture (DDD-friendly & testable)
• 🧩 Facade and fluent Uploader API
• 🔐 Support for signed/dynamic URLs

🚀 Installation

composer require m2code/file-manager

🛠 Publish Configuration

php artisan vendor:publish --tag=config --provider="M2code\FileManager\FileManagerServiceProvider"

📂 Basic Usage

Save file using facade (no config):

use M2code\FileManager\Facades\FileManager;

$result = FileManager::save($request->file('image'), 'uploads');
$result->filePath;

Save from base64 or raw SVG string:

use M2code\FileManager\Facades\FileManager;

// Base64 PNG
$base64Png = 'data:image/png;base64,...';
$png = FileManager::save($base64Png, 'uploads');

// Base64 SVG
$base64Svg = 'data:image/svg+xml;base64,...';
$svgFromBase64 = FileManager::save($base64Svg, 'uploads');

// Raw SVG string
$svg = '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64">...</svg>';
$svgRaw = FileManager::save($svg, 'uploads');

Upload image with processing:

use M2code\FileManager\Application\Uploader\ImageUploader;

$result = ImageUploader::make()
    ->blur()
    ->lowQuality()
    ->watermark()
    ->optimize('avif') // fallback to webp, or skipped if unsupported
    ->upload($request->file('photo'), 'uploads/images');

$result->variants->get('original')?->path;
$result->variants->get('optimized')?->path;
$result->variants->get('low_quality')?->path;
$result->variants->get('watermark')?->path;
$result->blurhash;

// Backward-compatible fields (still available):
$result->path;
$result->optimizedPath;
$result->lowQualityPath;
$result->watermarkPath;

SVG behavior in ImageUploader

$svg = '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64">...</svg>';

$result = ImageUploader::make()
    ->blur()
    ->lowQuality()
    ->watermark()
    ->optimize('avif')
    ->upload($svg, 'uploads/images');

// SVG only keeps original variant, raster processing is skipped:
$result->variants->get('original')?->path;   // not null
$result->variants->get('low_quality');       // null
$result->variants->get('optimized');         // null
$result->blurhash;                           // null

Delete files:

use M2code\FileManager\Facades\FileManager;

FileManager::delete('uploads/images/file.jpg');

FileManager::deleteMany([
    'uploads/images/a.jpg',
    'uploads/images/b.jpg',
]);

// Delete all variants from upload result:
FileManager::deleteVariants($result->variants);

📡 Get file URL

use M2code\FileManager\Facades\FileUrl;

$url = FileUrl::getUrl('uploads/images/image.jpg'); // Local or driver-specific
$signed = FileUrl::getSignedUrl('uploads/images/image.jpg', now()->addMinutes(5));

🗃 Supported Drivers

• ✅ Local (default)
• 🔜 S3, Firebase, Custom drivers

Configure in config/file-manager.php:

'default_driver' => 'local',
'default_deleter' => 'local',
'default_url_generator' => 'local',

🧩 Requirement: Imagick

This package uses intervention/image with Imagick driver for image processing features such as:

• Blurhash generation
• Optimized AVIF/WebP variant generation
• Low quality image variants
• Watermark (when enabled)

Imagick is required and declared in composer.json (ext-imagick).

⚙️ Why Imagick?

Compared to GD:

• Better image quality
• Faster processing for large images
• More advanced image manipulation capabilities

If you're serious about handling images, GD is… let's say, “minimum effort mode”.

💻 Installation Guide

🪟 Windows

1. Download Imagick DLL from: 👉 https://windows.php.net/downloads/pecl/releases/imagick/

2. Choose version that matches:

   • Your PHP version
   • Thread safety (TS/NTS)
   • Architecture (x64/x86)

3. Copy .dll file to: ext/

4. Enable in php.ini:

extension=imagick

1. Restart your web server

🍎 macOS

Using Homebrew:

brew install imagemagick
pecl install imagick

Then enable in php.ini:

extension=imagick

🐧 Linux (Ubuntu/Debian)

sudo apt update
sudo apt install imagemagick
sudo apt install php-imagick

Restart PHP / Web Server:

sudo service php-fpm restart
# or
sudo service apache2 restart

🐧 Linux (CentOS/RHEL)

sudo yum install epel-release
sudo yum install ImageMagick ImageMagick-devel
sudo pecl install imagick

Enable in php.ini:

extension=imagick

✅ Verify Installation

Run:

php -m | grep imagick

If installed correctly, you should see:

imagick

✅ Current Stable Flow

• Upload image (with optional variants)
• Upload from UploadedFile, base64 data URI, or raw SVG string
• Read variant paths from ImageUploadResult::variants
• Generate URL / signed URL
• Delete single file / batch / all variants safely

📄 License

MIT License © Marij Mokoginta (M2code)