Filament Backgrounds Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require swisnl/filament-backgrounds
   

   Publish the package assets (if customization is needed):

   php artisan vendor:publish --provider="Swisnl\FilamentBackgrounds\FilamentBackgroundsServiceProvider" --tag="filament-backgrounds"
   

2. Configuration Ensure your config/filament.php includes the package’s auth page customization:

   'auth' => [
       'pages' => [
           'login' => [
               'background' => true, // Enable backgrounds
           ],
       ],
   ],
   

3. First Use Case

   • After installation, the package automatically applies a random background image from the curated list to your Filament login/auth pages.
   • No additional code is required for basic functionality.

Implementation Patterns

Core Workflow

1. Dynamic Backgrounds The package injects a random background image from its curated list (resources/images) into Filament’s auth pages. Override this behavior by:

   • Customizing the Image List: Replace the default images by publishing assets and updating the config/filament-backgrounds.php:

     'images' => [
         'path' => 'custom/path/to/images',
     ],
     

   • Conditional Logic: Use Filament’s AuthPage hooks to dynamically select backgrounds:

     use Swisnl\FilamentBackgrounds\Facades\FilamentBackgrounds;
     
     Filament::serving(function () {
         FilamentBackgrounds::setBackground('path/to/specific-image.jpg');
     });
     

2. Theming Integration

   • CSS Overrides: Extend the package’s default styles by publishing the assets and modifying resources/css/filament-backgrounds.css:

     .filament-background {
         background-size: cover;
         opacity: 0.8; /* Example: Adjust opacity */
     }
     

   • Dark/Light Mode: Leverage Filament’s dark mode support by adding a dark: variant in your CSS:

     .filament-background.dark {
         filter: brightness(0.7);
     }
     

3. Localization & Accessibility

   • Fallbacks: Ensure accessibility by providing a fallback gradient or solid color if images fail to load:

     'fallback' => [
         'color' => '#f3f4f6', // Default Filament gray
         'gradient' => 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
     ],
     

   • Localized Descriptions: Add ARIA labels for screen readers:

     'attributes' => [
         'role' => 'img',
         'aria-label' => __('filament-backgrounds::messages.background_image'),
     ],
     

Gotchas and Tips

Pitfalls

1. Asset Paths

   • Issue: Hardcoding image paths in config/filament-backgrounds.php may break if the package is updated.
   • Fix: Use the package’s helper methods to resolve paths dynamically:

     FilamentBackgrounds::imagePath('custom-image.jpg');
     

2. Caching

   • Issue: Background images may not update immediately due to browser caching.
   • Fix: Append a query string to the image URL in your Blade template:

     <div style="background-image: url('{{ asset('images/background.jpg?t=' . time()) }}')">
     

3. Conflicts with Custom Auth Pages

   • Issue: If you’ve extended Filament’s auth pages, the package’s middleware may not apply.
   • Fix: Re-register the package’s middleware in your AppServiceProvider:

     public function boot()
     {
         Filament::auth()->middleware(function ($request) {
             FilamentBackgrounds::applyBackground();
         });
     }
     

Debugging Tips

1. Log Background Selection Enable debug logging to verify which image is being loaded:

   'debug' => env('FILAMENT_BACKGROUNDS_DEBUG', false),
   

   Check logs for entries like:

   [FilamentBackgrounds] Selected background: /path/to/image.jpg
   

2. Inspect Rendered HTML Use browser dev tools to verify the background-image CSS property is applied:

   .filament-background {
       background-image: url(/vendor/swisnl/filament-backgrounds/images/...);
   }
   

Extension Points

1. Custom Background Providers Create a custom provider to fetch backgrounds from an API or database:

   use Swisnl\FilamentBackgrounds\Contracts\BackgroundProvider;
   
   class ApiBackgroundProvider implements BackgroundProvider
   {
       public function getBackground(): string
       {
           return 'https://api.example.com/random-background';
       }
   }
   

   Register it in config/filament-backgrounds.php:

   'provider' => \App\Providers\ApiBackgroundProvider::class,
   

2. Event Listeners Listen for the filament-backgrounds.selected event to log or modify the selected background:

   FilamentBackgrounds::addListener(function (string $backgroundPath) {
       Log::info("Custom logic for: {$backgroundPath}");
   });
   

3. Testing Mock the background provider in tests:

   $this->app->bind(
       \Swisnl\FilamentBackgrounds\Contracts\BackgroundProvider::class,
       function () {
           return new class implements BackgroundProvider {
               public function getBackground(): string
               {
                   return 'tests/fixtures/background.jpg';
               }
           };
       }
   );