Filament Media Gallery Laravel Package

Getting Started

1. Install the Package:

   composer require ahmed-abdelrhman/filament-media-gallery
   

   No additional setup is required beyond auto-discovery.

2. First Use Case: Replace SpatieMediaLibraryImageEntry in a Filament Infolist with MediaGalleryEntry for a model using Spatie Media Library.

   use AhmedAbdelrhman\FilamentMediaGallery\Infolists\Components\MediaGalleryEntry;
   
   MediaGalleryEntry::make('gallery')
       ->collection('coach_gallery')
       ->label('Gallery Images');
   

3. Where to Look First:

   • README.md for basic syntax.
   • API Reference for method chaining (e.g., size(), rounded()).
   • Blade Component Docs if using standalone in custom views.

Implementation Patterns

Core Workflow

1. Define the Entry in Infolist:

   public static function infolist(Infolist $infolist): Infolist {
       return $infolist->schema([
           MediaGalleryEntry::make('media')
               ->collection('portfolio_images')
               ->label('Portfolio'),
       ]);
   }
   

2. Handle Related Models: Use fromRelation() when media belongs to a child model (e.g., User → Profile):

   MediaGalleryEntry::make('profile_media')
       ->collection('profile_photos')
       ->fromRelation('profile')
       ->visible(fn ($record) => $record->profile?->getMedia('profile_photos')->count() > 0);
   

3. Customize Appearance:

   • Fixed card size: ->size(300) (300×300px).
   • Circular thumbnails: ->rounded().
   • Example:

     MediaGalleryEntry::make('thumbnails')
         ->collection('thumbnails')
         ->size(150)
         ->rounded()
         ->label('Team Photos');
     

4. Standalone Usage: Embed in custom Blade/Livewire components:

   <x-media-gallery-viewer
       :media="$model->getMedia('gallery')"
       size="200"
       rounded="true"
   />
   

Integration Tips

• Media Conversions: Register thumbnail/preview conversions for optimal performance:

  public function registerMediaConversions(Media $media = null): void {
      $this->addMediaConversion('thumbnail')->width(150)->height(150)->nonQueued();
      $this->addMediaConversion('preview')->width(400)->height(400)->nonQueued();
  }
  

  The component prioritizes thumbnail → preview → original URL.

• Visibility Logic: Use visible() to conditionally show galleries:

  ->visible(fn ($record) => $record->hasMedia('gallery'))
  

• Panel Registration: Explicitly register the plugin in AdminPanelProvider for panel-level access:

  ->plugins([
      \AhmedAbdelrhman\FilamentMediaGallery\FilamentMediaGalleryPlugin::make(),
  ]);
  

• Dark Mode: No action needed—inherits Filament’s dark mode via Tailwind’s dark: variants.

Gotchas and Tips

Pitfalls

1. Relation Misconfiguration:

   • Error: Call to undefined method App\Models\User::getMedia().
   • Fix: Ensure fromRelation() points to a valid relation method. Verify the related model has HasMedia traits.

     // Correct: Relation exists and owns the media.
     ->fromRelation('coachProfile')
     

2. Empty Collections:

   • Issue: Gallery renders as empty if no media exists.
   • Fix: Add visibility checks:

     ->visible(fn ($record) => $record->getMedia('collection')->count() > 0)
     

3. PDF Handling:

   • Gotcha: PDFs open in a new tab but are excluded from the lightbox.
   • Workaround: Use ->visible(fn ($record) => $record->getMedia('collection')->where('mime_type', '!=', 'application/pdf')->count() > 0) to hide non-image galleries.

4. Performance with Large Galleries:

   • Problem: Alpine.js lightbox may lag with >50 images.
   • Tip: Limit collections or use Spatie’s limit():

     $record->getMedia('gallery')->limit(30);
     

Debugging

• Lightbox Not Working:

  • Check for Alpine.js conflicts (e.g., duplicate IDs). Ensure no other Alpine components are interfering.
  • Verify the media prop passes a valid Spatie\MediaLibrary\Models\Media collection.

• Broken Images:

  • Confirm media conversions are registered (thumbnail/preview).
  • Check file permissions for generated conversions (e.g., storage/app/public/convert/).

• CSS Overrides:

  • Publish views to customize:

    php artisan vendor:publish --tag=media-gallery-views
    

  • Override resources/views/vendor/filament-media-gallery/... to modify Tailwind classes.

Extension Points

1. Custom Lightbox:

   • Extend the Alpine.js logic in resources/views/vendor/filament-media-gallery/lightbox.blade.php to add animations or custom controls.

2. Additional MIME Types:

   • Modify the Blade component to support videos (e.g., video/mp4) by adding a new else-if branch for non-image/PDF media.

3. Lazy Loading:

   • Add loading="lazy" to image tags in the published view for better performance.

4. Accessibility:

   • Enhance the lightbox with ARIA attributes (e.g., aria-modal, aria-label) by editing the published Blade template.

Config Quirks

• Default Size: Omitting ->size() uses aspect-square, which may not suit all layouts. Explicitly set a size (e.g., ->size(250)) for consistency.

• Rounded vs. Default: ->rounded() applies rounded-full; omit it for rounded-lg. Test both in dark/light mode to ensure visual harmony.

• Plugin Registration: While auto-discovered, explicitly registering the plugin in AdminPanelProvider ensures it’s available across all panels.