README

Laravel File Manager for Filament

A comprehensive Laravel package for Filament v4 that provides advanced file management with automatic image resizing, compression, media metadata tracking, and seamless S3 integration. Built for high-performance applications handling large volumes of media content.

This package is developed and maintained by Kiran Timsina and RayzenTech.

Key Features

Core Features

🖼️ Automatic Image Resizing - Generate multiple sizes automatically on upload
🗜️ Smart Compression - WebP/AVIF conversion with configurable quality settings
🎭 AI Background Removal - Remove backgrounds from images using Cloud Run API
📊 Media Metadata Tracking - Track file sizes, dimensions, and compression stats
☁️ S3 Integration - Seamless AWS S3 storage with CDN support
⚡ Cache Control Headers - Configurable browser/CDN caching for optimal performance
🛠️ Artisan Commands - CLI tools for populating metadata with progress tracking
📁 Media Metadata Resource - Dedicated admin page for managing media with bulk operations
🖼️ Image Processor Page - Interactive tool for testing compression and processing settings

Advanced Processing

⚡ Dual API System - Fast Lambda API for compression, Cloud Run for AI features
🎨 Flexible Driver System - Choose between GD library or external APIs
🖼️ Interactive Processor - Test and process images directly in admin panel
📈 Bulk Operations - Process multiple files with detailed progress tracking
🔄 Smart Fallbacks - Automatic fallback to GD when API unavailable

Developer Experience

🎨 Custom Filament Components - MediaUpload and S3Image components
🔍 Advanced Resource Management - Built-in media metadata interface with bulk actions
🚀 Performance Optimized - Queue-based processing with chunked operations
🔧 Highly Configurable - Extensive configuration with environment variables
📝 Comprehensive CLI - Powerful artisan commands with progress tracking

About the Developers

Kiran Timsina is a full-stack developer specializing in Laravel and Filament applications. Connect on GitHub.

RayzenTech is a tech startup based in Nepal focused on creating smart business solutions. We specialize in automating complex processes and making them simple, from business automation to robotic process automation. Learn more at RayzenTech.

Requirements

PHP 8.1+
Laravel 10.0+
Filament 4.0+
AWS S3 configured (or S3-compatible storage)

Installation

Install via Composer:
```
composer require rayzenai/file-manager
```

Publish the configuration:

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

Publish and run migrations (for media metadata):

# Publish migration files to your app
php artisan vendor:publish --provider="Kirantimsina\FileManager\FileManagerServiceProvider" --tag="file-manager-migrations"

# Run the migrations
php artisan migrate

Configure your .env file:

# S3 Configuration (Required)
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_DEFAULT_REGION=your-region
AWS_BUCKET=your-bucket
AWS_URL=https://your-cdn-url.com

# Optional CDN URL (defaults to AWS_URL)
CDN_URL=https://your-cdn-url.com

# Cache Control Settings (Optional)
FILE_MANAGER_CACHE_ENABLED=true
FILE_MANAGER_CACHE_MAX_AGE=31536000  # 1 year in seconds
FILE_MANAGER_CACHE_VISIBILITY=public  # 'public' or 'private'
FILE_MANAGER_CACHE_IMMUTABLE=true     # Add immutable directive

# Compression Settings (Optional)
FILE_MANAGER_COMPRESSION_ENABLED=true
FILE_MANAGER_COMPRESSION_QUALITY=85 # 1-100, quality level
FILE_MANAGER_COMPRESSION_FORMAT=webp # webp, jpg, png, avif

# Compression Method Settings
FILE_MANAGER_COMPRESSION_METHOD=gd  # 'gd' for built-in PHP processing or 'api' for external service

# Primary API Settings (Fast compression, no background removal)
FILE_MANAGER_COMPRESSION_API_URL=https://your-aws-lambda-url.com/process-image
FILE_MANAGER_COMPRESSION_API_TOKEN=your-api-token
FILE_MANAGER_COMPRESSION_API_TIMEOUT=30

# Background Removal API Settings (Slower, supports background removal)
FILE_MANAGER_BG_REMOVAL_API_URL=https://your-gcp-run-url.com/process-image
FILE_MANAGER_BG_REMOVAL_API_TOKEN=your-bg-removal-token
FILE_MANAGER_BG_REMOVAL_API_TIMEOUT=60

Register the plugin in your Filament panel provider:

use Kirantimsina\FileManager\FileManagerPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FileManagerPlugin::make(),
        ]);
}

Configuration

The configuration file config/file-manager.php allows you to customize:

return [
    // CDN URL for serving files
    'cdn' => env('CDN_URL', env('AWS_URL', env('APP_URL'))),

    // Maximum upload dimensions
    'max-upload-height' => '5120', // pixels
    'max-upload-width' => '5120',  // pixels
    'max-upload-size' => '8192',   // KB

    // Model to directory mappings (supports full class names)
    'model' => [
        'App\Models\User' => 'users',       // Or use User::class
        'App\Models\Product' => 'products', // Or use Product::class
        'App\Models\Blog' => 'blogs',       // Or use Blog::class
        // Add your models here
    ],

    // Image sizes to generate
    // Set to empty array [] to disable automatic resizing completely
    'image_sizes' => [
        'icon' => 64,       // 64px height for small icons
        'small' => 120,     // 120px height for small thumbnails
        'thumb' => 240,     // 240px height for thumbnails
        'card' => 360,      // 360px height for card images
        'medium' => 480,    // 480px height for medium images
        'large' => 720,     // 720px height for large images
        'full' => 1080,     // 1080px height for full size
        'ultra' => 2160,    // 2160px height for ultra HD
    ],

    // Default thumbnail size for MediaColumn components
    'default_thumbnail_size' => env('FILE_MANAGER_DEFAULT_THUMBNAIL_SIZE', 'icon'),

    // Cache Control Headers for Images
    'cache' => [
        'enabled' => env('FILE_MANAGER_CACHE_ENABLED', true),
        
        // Cache duration in seconds
        // Common values:
        // 3600 = 1 hour
        // 86400 = 1 day  
        // 604800 = 1 week
        // 2592000 = 30 days
        // 31536000 = 1 year (default)
        'max_age' => env('FILE_MANAGER_CACHE_MAX_AGE', 31536000),
        
        // Cache visibility:
        // 'public' - Can be cached by browsers and CDNs
        // 'private' - Only cached by browsers, not CDNs
        'visibility' => env('FILE_MANAGER_CACHE_VISIBILITY', 'public'),
        
        // Immutable directive - tells browsers the file will never change
        // Recommended for versioned/hashed filenames
        'immutable' => env('FILE_MANAGER_CACHE_IMMUTABLE', true),
    ],

    // Compression settings
    'compression' => [
        'enabled' => env('FILE_MANAGER_COMPRESSION_ENABLED', true),
        'method' => env('FILE_MANAGER_COMPRESSION_METHOD', 'gd'), // 'gd' or 'api'
        'auto_compress' => env('FILE_MANAGER_AUTO_COMPRESS', true),
        'quality' => env('FILE_MANAGER_COMPRESSION_QUALITY', 85), // 1-100
        'format' => env('FILE_MANAGER_COMPRESSION_FORMAT', 'webp'), // webp, jpeg, jpg, png, avif
        'mode' => env('FILE_MANAGER_COMPRESSION_MODE', 'contain'), // contain, crop, cover
        'height' => env('FILE_MANAGER_COMPRESSION_HEIGHT', 1080),
        'width' => env('FILE_MANAGER_COMPRESSION_WIDTH', null),
        'threshold' => env('FILE_MANAGER_COMPRESSION_THRESHOLD', 100 * 1024), // 100KB

        // API settings for external compression
        'api' => [
            // Primary API (AWS Lambda - fast, no background removal)
            'url' => env('FILE_MANAGER_COMPRESSION_API_URL', ''),
            'token' => env('FILE_MANAGER_COMPRESSION_API_TOKEN', ''),
            'timeout' => env('FILE_MANAGER_COMPRESSION_API_TIMEOUT', 30),

            // Background removal API (Google Cloud Run - slower, supports bg removal)
            'bg_removal' => [
                'url' => env('FILE_MANAGER_BG_REMOVAL_API_URL', ''),
                'token' => env('FILE_MANAGER_BG_REMOVAL_API_TOKEN', ''),
                'timeout' => env('FILE_MANAGER_BG_REMOVAL_API_TIMEOUT', 60),
            ],
        ],
    ],

    // Media metadata tracking
    'media_metadata' => [
        'enabled' => env('FILE_MANAGER_METADATA_ENABLED', true),
        'track_file_size' => env('FILE_MANAGER_TRACK_FILE_SIZE', true),
        'track_dimensions' => env('FILE_MANAGER_TRACK_DIMENSIONS', true),
        'track_mime_type' => env('FILE_MANAGER_TRACK_MIME_TYPE', true),
        'model' => \Kirantimsina\FileManager\Models\MediaMetadata::class,
    ],
];

Usage in Models

Using the HasImages Trait

The HasImages trait automatically handles image resizing when images are uploaded or updated:

use Kirantimsina\FileManager\Traits\HasImages;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    use HasImages;

    protected $fillable = [
        'name',
        'image',        // Single image field
        'gallery',      // Multiple images field
    ];

    protected $casts = [
        'gallery' => 'array', // Cast array fields
    ];

    // Define which fields contain images for automatic resizing. Use `public` so that this is accessible by view helpers
    public function hasImagesTraitFields(): array
    {
        return ['image', 'gallery'];
    }
}

Key Features:

Automatically generates multiple sizes when images are saved
Handles both single images and arrays of images
Smart diffing - only resizes truly new images
Automatic cleanup of old images when replaced
Queue-based processing for better performance

Usage in Filament Resources

MediaUpload Component

The MediaUpload component extends Filament's FileUpload with automatic compression and metadata tracking:

use Kirantimsina\FileManager\Forms\Components\MediaUpload;

// Example 1: Convert to WebP with custom quality
MediaUpload::make('image')
    ->label('Product Image')
    ->quality(90)               // Compression quality, capped at 95
    ->toWebp()                  // Convert to WebP format

// Example 2: Compress but keep original format (JPEG stays JPEG, PNG stays PNG)
MediaUpload::make('photo')
    ->keepOriginalFormat()      // Compress but maintain original format
    ->quality(85)               // Still applies compression

// Example 3: Upload without ANY processing
MediaUpload::make('document')
    ->uploadOriginal()          // Skip all processing - no compression, no conversion

// Example 4: Full featured upload with background removal
MediaUpload::make('product_image')
    ->toAvif()                  // Convert to AVIF format
    ->quality(90)               // High quality
    ->removeBg()                // Remove background (API required)
    ->driver('api')             // Use API compression
    ->trackMetadata()           // Track file metadata
    ->multiple()                // Allow multiple files

Available Methods:

quality(int $quality): Set compression quality (1-95, default: from config)
format(string $format): Set output format ('webp', 'jpeg', 'jpg', 'png', 'avif', 'original')
toWebp(): Convert to WebP format
toAvif(): Convert to AVIF format, might not be avaialble with GD
keepOriginalFormat(): Compress but keep the original file format
uploadOriginal(): Skip ALL processing - no compression, no resizing, no format conversion
trackMetadata(): Enable/disable metadata tracking
removeBg(): Enable background removal (API only)
driver('gd'|'api'): Choose compression driver
resize(): Enable Filament's built-in resizing (opposite of uploadOriginal)

Important Notes:

Compression: Images are automatically compressed when enabled in config (unless uploadOriginal() is called)
Format Control: Use toWebp(), toAvif(), or format() to override config format
Upload Original: Call uploadOriginal() to skip ALL processing and upload file exactly as-is

Features:

Smart compression with configurable output format (WebP/JPEG/PNG/AVIF)
AI-powered background removal (API only)
Metadata tracking with compression stats
Supports both images and videos
SEO-friendly file naming

Background Removal

The removeBg() method enables AI-powered background removal for images. This feature requires external API configuration (specifically the background removal API endpoint) and is not available with the GD library method.

Compression Drivers

You can specify which compression driver to use:

// Use GD library (built-in PHP processing)
MediaUpload::make('image')
    ->driver('gd')

// Use external API service
MediaUpload::make('image')
    ->driver('api')

The package supports two external APIs:

Primary API (AWS Lambda): Fast compression without background removal
Background Removal API (Google Cloud Run): Slower but supports AI background removal

// Enable background removal with boolean
MediaUpload::make('image')
    ->removeBg(true)

// Or use the convenience method
MediaUpload::make('image')
    ->withoutBackground()

// Dynamic background removal with closure
use Filament\Forms\Components\Toggle;

Toggle::make('remove_bg')
    ->label('Remove Background')
    ->dehydrated(false)  // Don't save to database

MediaUpload::make('image')
    ->removeBg(fn (Get $get) => $get('remove_bg'))

Important: When using Toggle fields for background removal control, use dehydrated(false) or handle the field in mutateFormDataBeforeCreate() and mutateFormDataBeforeSave() to prevent database errors:

// In your Filament Resource
protected function mutateFormDataBeforeCreate(array $data): array
{
    unset($data['remove_bg']);
    return $data;
}

protected function mutateFormDataBeforeSave(array $data): array
{
    unset($data['remove_bg']);
    return $data;
}

MediaModalColumn and MediaUrlColumn

Display images in tables with different interaction styles:

MediaModalColumn

Display images with modal preview and optional editing capabilities:

use Kirantimsina\FileManager\Tables\Columns\MediaModalColumn;

// Basic usage with modal preview
MediaModalColumn::make('image_file_name')
    ->label('Product Image')
    ->thumbnailSize('small')
    ->modalSize('large')
    ->allowEdit() // Enable editing in modal

// With custom heading and relationship
MediaModalColumn::make('attachment_file_name')
    ->label('Attachments')
    ->relationship('attachments')
    ->heading('View Attachments')
    ->multiple() // Handle multiple images
    ->downloadable() // Allow downloads
    ->previewable() // Enable preview

// Legacy dot notation (still supported)
MediaModalColumn::make('product.image_file_name')
    ->label('Product Image')
    ->thumbnailSize('medium')

MediaUrlColumn

Display images that link to a dedicated media page:

use Kirantimsina\FileManager\Tables\Columns\MediaUrlColumn;

// Basic usage - links to media page
MediaUrlColumn::make('image_file_name')
    ->label('Product Image')
    ->thumbnailSize('small')
    ->openInNewTab() // Open link in new tab

// With relationship
MediaUrlColumn::make('featured_image')
    ->label('Featured Image')
    ->relationship('media')
    ->thumbnailSize('card')

Common Methods (both components):

thumbnailSize(): Set thumbnail size ('icon', 'small', 'medium', 'large', etc.)
label(): Column label
relationship(): Name of the Eloquent relationship (for HasMany, HasOne, BelongsTo)
showMetadata(): Show file metadata in tooltip
viewCountField(): Field to track view counts

MediaModalColumn specific methods:

modalSize(): Size for modal preview images
heading(): Modal heading (closure or string)
allowEdit(): Enable editing images in modal
multiple(): Handle multiple images
downloadable(): Allow image downloads
previewable(): Enable image preview
uploadOriginal(): Upload file as-is without any processing (default: false)

MediaUrlColumn specific methods:

openInNewTab(): Open media page in new tab (default: true)

Features:

Direct field access: Works with model attributes directly
Relationship support: Access images through Eloquent relationships
Dot notation: Legacy support for nested relationships
Modal editing: View and replace images through modal interface
Multiple images: Handles both single and multiple image fields
Smart loading: Automatically loads relationships to prevent N+1 queries
Metadata display: Optional file size and type information

Relationship Support (v4.3+):

The relationship parameter allows you to display and manage images from related models:

// In your model
class CartItem extends Model
{
    public function attachments(): HasMany
    {
        return $this->hasMany(AttachmentFile::class);
    }
}

// In your Filament resource
MediaColumn::make(
    field: 'attachment_file_name',  // Field on the AttachmentFile model
    relationship: 'attachments',     // Relationship method name
    showInModal: true
)

This will:

Display all attachment images in the table column
Allow viewing all images in a modal
Enable uploading new images that will replace existing attachments
Handle HasMany, HasOne, and BelongsTo relationships automatically

Default Thumbnail Size

You can configure the default thumbnail size for all MediaColumn components by setting the default_thumbnail_size in your configuration:

// config/file-manager.php
'default_thumbnail_size' => 'thumb', // Use 'thumb' instead of 'icon' as default

Or via environment variable:

FILE_MANAGER_DEFAULT_THUMBNAIL_SIZE=thumb

Individual columns can still override this default by calling the thumbnailSize() method:

MediaModalColumn::make('image')
    ->thumbnailSize('large') // This overrides the default

// Or for URL column
MediaUrlColumn::make('image')
    ->thumbnailSize('large') // This overrides the default

S3Image Column

Display images in tables with modal preview:

use Kirantimsina\FileManager\Tables\Columns\S3Image;

S3Image::make('image')
    ->label('Image')
    ->size('medium')     // Use specific size: 'small', 'medium', 'large'
    ->square()           // Square aspect ratio
    ->circular()         // Circular mask

Media Metadata Management

The package includes a powerful Filament resource for comprehensive media management.

Dashboard Features

Navigation & Monitoring

Smart Navigation Badge: Real-time count of large files (>500KB)
- 🔵 Info: 1-50 large files
- 🟡 Warning: 51-100 large files
- 🔴 Danger: 100+ large files
Automatic cache refresh every 5 minutes

File Management

Comprehensive file listing with:
- Model type and ID
- Field name
- File size with human-readable format
- Image dimensions (width × height)
- MIME type with color-coded badges
- Creation and update timestamps

Advanced Filtering

Quick Filters:
- Large Files (>500KB)
- Very Large Files (>2MB)
Model Type Filter: Filter by specific models
File Type Filter: Filter by MIME type
Search: Find files by name or path

Individual File Actions

Open in Panel: Navigate directly to the parent resource
Resize: Generate all configured size variations
Compress: Apply custom compression settings
Rename: Update file names in database
Delete Resized: Remove all size variations

Bulk Operations

Bulk Compress

Select multiple images for compression
Choose output format (WebP, AVIF, JPEG, PNG)
Set compression quality (50-100%)
Option to replace originals
Detailed progress reporting

Bulk Resize

Generate all size variations for selected images
Queue-based processing for performance
Progress notifications

Bulk Delete Resized

Remove all resized versions for selected images
Confirmation dialog with warnings
Batch processing with result summary

Image Processor Page

The MediaMetadata resource includes a dedicated Image Processor page - a powerful tool for testing and optimizing your image processing pipeline.

Features:

Upload & Process

Drag-and-drop or click to upload images up to 10MB
Support for JPEG, PNG, WebP, and AVIF formats
Real-time preview of uploaded images

Processing Options

Format Selection: Convert between WebP, JPEG, PNG, and AVIF
Quality Control: Adjust compression from 50% to 100%
Resizing: Set custom dimensions with multiple resize modes
Background Removal: AI-powered background removal (when API configured)

Compression Methods

Auto: Intelligently selects the best available method
Lambda API: Fast compression via AWS Lambda
Cloud Run API: Advanced features including background removal
GD Library: Local processing fallback

Results & Analytics

Side-by-side comparison of original vs processed
Detailed statistics:
- Original and compressed file sizes
- Space saved (KB and percentage)
- Final dimensions
- Processing method used
Download processed images directly

Use Cases:

Test compression settings before applying to production
Optimize images for specific use cases
Validate API configuration and performance
Compare processing methods (GD vs API)
Generate samples for documentation

Service Methods

Using the FileManager Facade

use App\Models\Product;
use Kirantimsina\FileManager\Facades\FileManager;

// Upload a file
$result = FileManager::upload(
    Product::class,      // model class
    $uploadedFile,       // file
    'summer-sale',       // tag (optional)
    false,               // fit (optional, default: false)
    true,                // resize (optional, default: true)
    false,               // webp (optional, default: false)
    false                // reencode (optional, default: false)
);
$path = $result['file']; // Get the file path from result

// Upload multiple files
$result = FileManager::uploadImages(
    Product::class,      // model class
    $uploadedFiles,      // files array
    'gallery',           // tag (optional)
    false,               // fit (optional)
    true                 // resize (optional)
);
$paths = $result['files']; // Get array of file paths

// Upload base64 encoded image
$result = FileManager::uploadBase64(
    Product::class,      // model class
    $base64String,       // base64 image
    'user-upload',       // tag (optional)
    false,               // fit (optional)
    true                 // resize (optional)
);
$path = $result['file']; // Get the file path from result

// Move temp file without resizing
$path = FileManager::moveTempImageWithoutResize(
    Product::class,      // model class
    'temp/abc123.jpg'    // temp file path
);

// Move temp file with automatic resizing
$path = FileManager::moveTempImage(
    Product::class,      // model class
    'temp/abc123.jpg'    // temp file path
);

// Delete image and all its sizes
FileManager::deleteImage('products/image.jpg');

// Delete multiple images
FileManager::deleteImagesArray(['products/img1.jpg', 'products/img2.jpg']);

// Get SEO-friendly filename
$filename = FileManager::filename(
    file: $uploadedFile,
    tag: 'product-name',
    extension: 'webp'
);

// Get image URL with specific size
$url = FileManager::getMediaPath('products/image.jpg', 'medium');

// Get CDN URL
$cdnUrl = FileManager::mainMediaUrl();

// Get upload directory for a model
$directory = FileManager::getUploadDirectory(Product::class);

// Get configured image sizes
$sizes = FileManager::getImageSizes();

Image Compression Service

use Kirantimsina\FileManager\Services\ImageCompressionService;

$service = new ImageCompressionService();

// Compress and save
$result = $service->compressAndSave(
    sourcePath: '/tmp/upload.jpg',
    destinationPath: 'products/compressed.webp',
    quality: 85,
    height: 1080,
    width: null,  // Auto-calculate
    format: 'webp',
    mode: 'contain',
    disk: 's3',
    removeBg: false  // Set to true for background removal (API only)
);

// Compress with background removal (requires API configuration)
$result = $service->compressAndSave(
    sourcePath: '/tmp/product.jpg',
    destinationPath: 'products/product-no-bg.webp',
    quality: 90,
    height: 720,
    width: null,
    format: 'webp',
    mode: 'contain',
    disk: 's3',
    removeBg: true  // Requires FILE_MANAGER_COMPRESSION_METHOD=api
);

// Compress existing S3 file
$result = $service->compressExisting(
    filePath: 'products/large-image.jpg',
    quality: 80
);

Compression Methods:

GD Library (method: 'gd'): Built-in PHP image processing. Supports resizing, format conversion, and basic compression. Does not support background removal.
External API (method: 'api'): Uses external image processing service. Supports all GD features plus AI-powered background removal. The package intelligently routes requests:
- Standard compression requests go to the primary API (faster)
- Background removal requests go to the specialized background removal API (slower but more features)
- Falls back to GD if API is unavailable

Queue Jobs

The package uses queued jobs for better performance:

# Process resize jobs
php artisan queue:work

# Monitor queue
php artisan queue:monitor

Available Jobs:

ResizeImages - Generate multiple sizes for uploaded images
DeleteImages - Clean up images and all their sizes
PopulateMediaMetadataJob - Populate media metadata for existing images

Artisan Commands

Populate Media Metadata

If you have existing images in your database before installing this package, you can populate their metadata:

# Populate metadata for all configured models
php artisan file-manager:populate-metadata

# Populate metadata for a specific model (supports both short and full class names)
php artisan file-manager:populate-metadata --model=Product
php artisan file-manager:populate-metadata --model="App\Models\Product"

# Populate metadata for a specific field
php artisan file-manager:populate-metadata --model=Product --field=image_file_name

# Process with custom chunk size (default is 1000)
php artisan file-manager:populate-metadata --chunk=500

# Process synchronously without queue (good for testing)
php artisan file-manager:populate-metadata --model=Product --sync --chunk=100

# Dry run to see what would be processed
php artisan file-manager:populate-metadata --dry-run

Improvements in the latest version:

Better model class resolution (supports both short names and full namespaces)
Progress bar for tracking processing status
Improved error handling and reporting
Memory-efficient chunked processing
Dry-run mode for testing
Synchronous mode for immediate processing

This command will:

Scan configured models that use the HasImages trait
Process records in batches to avoid memory issues
Create MediaMetadata records for existing images
Dispatch jobs to handle large datasets efficiently
Extract file information including size, mime type, and dimensions

Update Cache Headers for Existing Images

Retroactively add cache control headers to existing images in S3:

# Update all images in all directories
php artisan file-manager:update-cache-headers

# Update images in a specific directory
php artisan file-manager:update-cache-headers products
php artisan file-manager:update-cache-headers users

# Preview changes without applying them (dry run)
php artisan file-manager:update-cache-headers --dry-run

# Limit the number of files to process (useful for testing)
php artisan file-manager:update-cache-headers --limit=100

# Show detailed output for each file processed
php artisan file-manager:update-cache-headers --detailed

# Combine options
php artisan file-manager:update-cache-headers products --dry-run --limit=10 --detailed

Features:

✅ Progress bar showing real-time progress
🔍 Dry run mode to preview changes
📁 Directory-specific updates
🎯 Limit option for batch processing
📝 Detailed output mode showing each file processed
📊 Summary report with success/error counts
🚀 Automatically detects all image directories from config

How it works:

Uses S3's copyObject API to update metadata without re-uploading files
Applies cache control settings from your config
Sets proper Content-Type based on file extension
Processes original images and all resized versions

This command is essential if you have images uploaded before cache headers were implemented, ensuring all your images benefit from optimal browser and CDN caching.

💡 Tip: Verifying Cache Headers

To check if cache headers are properly set on your images, use curl:

# Check headers for a specific image
curl -I https://your-cdn.amazonaws.com/products/image.jpg | grep -E "Cache-Control|Content-Type"

# Expected output:
# Cache-Control: public, max-age=31536000, immutable
# Content-Type: image/jpeg

Helper Functions

// Get image URL with specific size
$url = getImagePath('products/image.jpg', 'medium');

// Get CDN URL
$url = getCdnUrl('products/image.jpg');

// Check if file is an image
$isImage = isImageFile('document.pdf'); // false

Advanced Usage

Custom Image Sizes

Define custom sizes in your config:

'image_sizes' => [
    'thumbnail' => 150,
    'card' => 400,
    'hero' => 1920,
    // Add your custom sizes
],

Disabling Automatic Resizing

To completely disable automatic image resizing, set the image_sizes config to an empty array:

'image_sizes' => [],

This is useful when:

You want to handle image resizing manually
You're working with vector graphics or images that shouldn't be resized
You want to optimize storage by keeping only original images
You're using an external service for image processing

Exclude Certain Fields from Resizing

Videos and certain file types are automatically excluded from resizing.

Handling Nested Arrays

For complex data structures like checkout items:

// The trait handles nested arrays intelligently
$checkout->items = [
    ['product_id' => 1, 'images' => ['image1.jpg', 'image2.jpg']],
    ['product_id' => 2, 'images' => ['image3.jpg']],
];

Troubleshooting

Images not resizing

Ensure queue workers are running: php artisan queue:work
Check that model directories are configured in config/file-manager.php
Verify S3 permissions allow reading and writing

Duplicate resize jobs

Use moveTempImageWithoutResize() when the model has HasImages trait
The trait automatically handles resizing on create/update

WebP conversion failing

Ensure GD or ImageMagick PHP extensions are installed
Check PHP memory limit for large images

Performance Tips

Use queues for image processing to avoid blocking requests
Enable compression for automatic file size optimization
Configure CDN for faster content delivery
Set appropriate thresholds to avoid compressing small files
Use WebP format for 25-35% smaller file sizes
Configure cache headers for optimal browser and CDN caching:
- Set max_age to 31536000 (1 year) for versioned/hashed filenames
- Use public visibility for CDN caching
- Enable immutable for static assets that never change

Cache Control Configuration

The package automatically adds cache headers to all uploaded images for optimal performance:

# Disable cache headers (not recommended)
FILE_MANAGER_CACHE_ENABLED=false

# Custom cache duration (in seconds)
FILE_MANAGER_CACHE_MAX_AGE=86400   # 1 day
FILE_MANAGER_CACHE_MAX_AGE=604800  # 1 week
FILE_MANAGER_CACHE_MAX_AGE=2592000 # 30 days

# Private caching (browser only, no CDN)
FILE_MANAGER_CACHE_VISIBILITY=private

# Allow revalidation (for frequently updated images)
FILE_MANAGER_CACHE_IMMUTABLE=false

All images uploaded to S3 will automatically include these cache headers:

Cache-Control: public, max-age=31536000, immutable (default)
Proper Content-Type based on actual file format
Optimized for CDN edge caching

Changelog

Please see CHANGELOG for recent changes.

Contributing

Contributions are welcome! Please see CONTRIBUTING for details.

Security

If you discover any security issues, please email timsinakiran@gmail.com instead of using the issue tracker.

rayzenai / file-manager

Maintainers

Details

README

Laravel File Manager for Filament

Key Features

Core Features

Advanced Processing

Developer Experience

About the Developers

Requirements

Installation

Configuration

Usage in Models

Using the HasImages Trait

Usage in Filament Resources

MediaUpload Component

Background Removal

Compression Drivers

MediaModalColumn and MediaUrlColumn

MediaModalColumn

MediaUrlColumn

Default Thumbnail Size

S3Image Column

Media Metadata Management

Dashboard Features

Navigation & Monitoring

File Management

Advanced Filtering

Individual File Actions

Bulk Operations

Bulk Compress

Bulk Resize

Bulk Delete Resized

Image Processor Page

Features:

Use Cases:

Service Methods

Using the FileManager Facade

Image Compression Service

Queue Jobs

Artisan Commands

Populate Media Metadata

Update Cache Headers for Existing Images

Helper Functions

Advanced Usage

Custom Image Sizes

Disabling Automatic Resizing

Exclude Certain Fields from Resizing

Handling Nested Arrays

Troubleshooting

Images not resizing

Duplicate resize jobs

WebP conversion failing

Performance Tips

Cache Control Configuration

Changelog

Contributing

Security

Credits

License

Support