Download the PHP package rayzenai/file-manager without Composer

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

1. Install via Composer:

2. Publish the configuration:

3. Publish and run migrations (for media metadata):

4. Configure your .env file:

5. Register the plugin in your Filament panel provider:

Configuration

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

Usage in Models

Using the HasImages Trait

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

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

SEO Title Support

The package includes built-in SEO title functionality for better search engine optimization of media files:

Configuration:

Control which models receive SEO titles in config/file-manager.php:

MediaUpload Component

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

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:

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

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

MediaModalColumn and MediaUrlColumn

Display images in tables with different interaction styles:

MediaModalColumn

Display images with modal preview and optional editing capabilities:

MediaUrlColumn

Display images that link to a dedicated media page:

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:

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 Sizes

You can configure default sizes for MediaColumn components in your configuration:

Or via environment variables:

Available size configurations:

• default_thumbnail_size: Used for thumbnail displays in table columns (default: 'icon')
• default_card_size: Used for larger preview displays like modals (default: 'card')

Individual columns can still override these defaults (limited to thumbnail size only):

S3Image Column

Display images in tables with modal preview:

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:
  • Inefficient Images (>0.35 bytes per pixel, >10KB) - Smart filter for images that would benefit from WebP compression
  • 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

1. Open in Panel: Navigate directly to the parent resource
2. Resize: Generate all configured size variations
3. Compress: Apply custom compression settings
4. Rename: Update file names in database
5. 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:

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

Service Methods

Using the FileManager Facade

Image Compression Service

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:

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

The package provides several powerful Artisan commands for managing your media files and metadata:

Manage Image Sizes

Add or remove image sizes for all media files in the media_metadata table. This command is useful when you need to add a new size to your configuration or clean up unused sizes.

Adding a New Size

Removing an Existing Size

Key Features

• Safe Operations: Dry-run mode lets you preview changes before executing
• Progress Tracking: Real-time progress bar shows current status
• Batch Processing: Configurable chunk sizes for memory efficiency
• Error Handling: Detailed error reporting for failed operations
• S3 Integration: Automatically handles S3 file creation and deletion
• Format Support: Uses configured compression format (WebP, JPEG, PNG, AVIF)

Important Notes

• Configuration First Approach: The command enforces configuration updates before operations:

  • Adding: Blocks execution if size not in config, requires you to add it first
  • Removing: Blocks execution if size still in config, requires you to remove it first
  • This prevents orphaned files and ensures configuration consistency

• Two-Step Process:

  1. Update your configuration in config/file-manager.php
  2. Run the command to process the files
• Storage Requirements: Adding sizes will increase storage usage as new files are created
• Processing Time: Large datasets may take considerable time to process
• File Cleanup: Removing sizes permanently deletes the associated image files

Example Output

Blocked when size not in config:

Success after adding to config:

Refresh All Media

Queue refresh jobs to update metadata for all media files. This command checks file metadata, dimensions, and synchronizes database records with actual file states in S3 storage.

What It Checks

• File Size Changes: Updates file_size if different from S3
• MIME Type Changes: Updates mime_type based on current file
• Image Dimensions: Recalculates width/height for image files
• Model References: Verifies parent models still reference the file

Key Features

• Queued Processing: Uses background jobs to avoid timeouts
• Progress Tracking: Real-time notifications every 10 completed jobs
• Batch Processing: Configurable chunk sizes for memory efficiency
• Safe Operations: Dry-run mode to preview changes
• Error Handling: Detailed logging and retry logic
• Non-Destructive: Only updates metadata, doesn't modify files

Example Output

GUI Alternative

You can also use the "Refresh All (Queued)" bulk action in the MediaMetadata admin panel to refresh selected records through the UI.

Populate SEO Titles

Generate SEO-optimized titles for existing media files based on their parent model data:

Features:

• Intelligently extracts titles from parent model fields (meta_title, seo_title, name, title, etc.)
• Removes special characters from beginning/end of titles
• Respects configuration for enabled/excluded models
• Processes large datasets efficiently with chunked operations
• Shows detailed breakdown by model type

Update SEO Titles

Update SEO titles when parent model data changes:

Automatic Updates with HasImages Trait

The HasImages trait now includes automatic SEO title updates. Simply define which field to use for SEO titles in your model:

The HasImages trait now provides:

• Automatic image resizing for configured sizes
• Media metadata tracking
• Automatic SEO title updates when the field returned by seoTitleField() changes

How SEO Titles Work:

• Opt-in system: Only models with a seoTitleField() method will have SEO titles
• No configuration needed: The presence of the method indicates the model wants SEO titles
• Null is fine: If the specified field is null/empty, the SEO title will be null
• Clean and explicit: Each model declares exactly which field to use

Important Notes:

• Models without seoTitleField() method won't have SEO titles (intentional)
• Return a single field name, not conditional logic
• This is perfect for models where SEO is important (Product, Blog, Category) while internal models (Order, User, CartItem) simply don't define the method

Example for different models:

Populate Media Metadata

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

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:

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

Remove Duplicate Media Metadata

Clean up duplicate media metadata records from your database:

What it does:

• Identifies duplicate records based on: mediable_type + mediable_id + mediable_field + file_name
• Shows you a preview of duplicates with counts and details
• Keeps the oldest record in each duplicate group (by created_at and id)
• Removes all other duplicates in each group
• Provides verification that cleanup was successful

Features:

• 🔍 Dry run mode to preview what will be removed
• 📊 Detailed reporting showing duplicate groups and counts
• 📋 Sample preview of duplicates before removal
• ✅ Verification to confirm cleanup was successful
• 🚀 Progress bar for large datasets
• 💾 Safe operation - always keeps the oldest record
• 🤖 Non-interactive mode with --force flag for automation

Example output:

This command is useful when:

• You've imported data that created duplicate metadata entries
• Migration issues caused duplicate records
• Multiple processes created metadata for the same files
• You want to clean up your database before important operations

Update Cache Headers for Existing Images

Retroactively add cache control headers to existing images in S3:

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:

Helper Functions

Advanced Usage

Custom Image Sizes

Define custom sizes in your config:

Disabling Automatic Resizing

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

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:

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

1. Use queues for image processing to avoid blocking requests
2. Enable compression for automatic file size optimization
3. Configure CDN for faster content delivery
4. Set appropriate thresholds to avoid compressing small files
5. Use WebP format for 25-35% smaller file sizes
6. 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:

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 [email protected] instead of using the issue tracker.

Credits

• Kiran Timsina
• RayzenTech
• All Contributors

License

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

Support

For support, please open an issue on GitHub.