Filament Image Compare Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require pxlrbt/filament-image-compare
   

   Ensure your Laravel project is using Filament v3 (check compatibility in the README).

2. First Use Case: Add the entry to a Filament Resource or Page via an Infolist:

   use Pxlrbt\FilamentImageCompare\ImageCompareEntry;
   
   Infolist::columns(2)->schema([
       ImageCompareEntry::make()
           ->leftImage(fn ($record) => $record->before_image)
           ->rightImage(fn ($record) => $record->after_image),
   ]);
   

3. Where to Look First:

   • Preview: Check the GitHub preview.gif for visual behavior.
   • Source Code: Focus on ImageCompareEntry.php for configuration options and default props.
   • Tests: Review tests/ for edge cases (e.g., missing images, non-square ratios).

Implementation Patterns

Core Workflows

1. Dynamic Image Sources: Use closures for flexibility (e.g., API responses, computed paths):

   ImageCompareEntry::make()
       ->leftImage(fn ($record) => $record->getOriginal('image_before'))
       ->rightImage(fn ($record) => Storage::disk('s3')->url($record->image_after));
   

2. Conditional Rendering: Hide the entry if either image is missing:

   ImageCompareEntry::make()
       ->leftImage(fn ($record) => optional($record->before_image)->path)
       ->rightImage(fn ($record) => optional($record->after_image)->path)
       ->hidden(fn ($record) => !$record->before_image || !$record->after_image);
   

3. Custom Styling: Override default CSS via Filament’s tailwind config or inline styles:

   ->extraAttributes(['class' => 'h-64 w-full'])
   ->extraAttributes(['style' => 'border: 2px solid #3b82f6'])
   

4. Integration with Forms: Pair with FileUpload for editable comparisons (e.g., A/B testing):

   use Filament\Forms\Components\FileUpload;
   
   Forms\Components\Group::make([
       FileUpload::make('before_image')->image(),
       FileUpload::make('after_image')->image(),
   ]);
   

Advanced Patterns

• Lazy Loading: Use ->image() on FileUpload to defer image processing.
• Aspect Ratio Locking: Ensure consistent sizing with ->height()/->width():

  ->height('300px')->width('auto')
  

• Localization: Translate labels (e.g., "Before" → "Anterior") via Filament’s __() helper.

Gotchas and Tips

Pitfalls

1. Image Paths:

   • Gotcha: Relative paths (e.g., storage/app/image.jpg) may break in production.
   • Fix: Use absolute URLs or Storage::url():

     ->leftImage(fn ($record) => Storage::disk('public')->url($record->path))
     

2. Missing Images:

   • Gotcha: Unset images render as broken placeholders.
   • Fix: Provide fallbacks:

     ->leftImage(fn ($record) => $record->before_image ?? 'path/to/fallback.jpg')
     

3. CORS Issues:

   • Gotcha: Directly referencing external images (e.g., CDN) may fail due to CORS.
   • Fix: Proxy images via a Laravel route or use imgix/Cloudinary for dynamic URLs.

4. Filament Version Mismatch:

   • Gotcha: Package assumes Filament v3+. Upgrading may require adjustments to schema() syntax.

Debugging Tips

• Inspect Rendered HTML: Use browser dev tools to verify image sources (src attributes).
• Check Filament Logs: Enable debug mode in config/filament.php for entry rendering errors.
• Test Edge Cases: Manually trigger missing images or malformed paths in tests.

Extension Points

1. Custom Comparison Logic: Override the default slider behavior by extending the component:

   class CustomCompareEntry extends ImageCompareEntry {
       protected function getView(): string {
           return 'custom-image-compare';
       }
   }
   

2. Add Metadata: Include alt text or captions via extraAttributes:

   ->extraAttributes(['aria-label' => 'Before/After Comparison'])
   

3. Server-Side Processing: Use Laravel queues to generate comparison thumbnails for performance:

   ->leftImage(fn ($record) => route('images.compare', ['id' => $record->id, 'side' => 'left']))
   

4. Accessibility: Add keyboard navigation or ARIA labels for screen readers:

   ->extraAttributes([
       'role' => 'region',
       'aria-label' => 'Side-by-side image comparison',
   ])