Banner Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require kenepa/banner:^1.0
   

   Publish the package configuration and migrations:

   php artisan vendor:publish --provider="Kenepa\Banner\BannerServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Kenepa\Banner\BannerServiceProvider" --tag="migrations"
   php artisan migrate
   

2. First Banner Register the banner in app/Providers/AppServiceProvider.php:

   use Kenepa\Banner\Facades\Banner;
   
   public function boot()
   {
       Banner::add('welcome', [
           'title' => 'Welcome!',
           'message' => 'New updates available.',
           'type' => 'success',
       ]);
   }
   

3. Display in Blade

   @banner('welcome')
   

Implementation Patterns

Core Workflows

1. Dynamic Banner Management

   • Use Banner::add() in service providers or controllers for runtime banners.
   • Example: Flash notifications after form submission:

     Banner::add('form_success', [
         'title' => 'Success!',
         'message' => 'Your changes have been saved.',
         'type' => 'success',
         'timeout' => 5000, // Auto-dismiss in 5s
     ]);
     

2. Conditional Rendering

   • Check banner existence before rendering:

     @if(Banner::exists('welcome'))
         @banner('welcome')
     @endif
     

3. Global vs. Local Banners

   • Global: Registered in AppServiceProvider (persists across sessions).
   • Local: Registered in controllers (session-scoped).

4. Integration with Filament (V5)

   • Use Banner::add() in Filament V5 policies, actions, or resources:

     public function handle()
     {
         Banner::add('filament_action', [
             'title' => 'Action Complete',
             'message' => 'Your task was processed.',
             'type' => 'info',
         ]);
         return redirect()->back();
     }
     

   • For Filament notifications, leverage the package alongside Filament's native notifications for a cohesive UX.

5. Multi-Language Support (French Added)

   • Use built-in French translations:

     Banner::add('welcome', [
         'title' => __('banner.welcome.title'),
         'message' => __('banner.welcome.message'),
     ]);
     

   • Ensure app.php locale settings are configured for French ('locale' => 'fr').

Advanced Patterns

1. Custom Banner Types Extend the default types (success, danger, warning, info) by publishing the config and adding:

   'types' => [
       'custom' => 'bg-blue-500 text-white',
   ],
   

2. Banner Storage Override storage (e.g., cache) in config/banner.php:

   'driver' => 'cache',
   

3. Programmatic Removal Clear banners in middleware or controllers:

   Banner::remove('welcome');
   Banner::clear(); // Remove all
   

4. API Responses Attach banners to API responses (requires custom middleware):

   return response()->json($data, 200)->withBanner('welcome');
   

Gotchas and Tips

Common Pitfalls

1. Session Dependency

   • Banners registered in AppServiceProvider persist until manually cleared. Use Banner::clear() in logout middleware if needed.

2. Blade Cache Conflicts Clear Blade cache after adding new banners:

   php artisan view:clear
   

3. Type Mismatch Errors Ensure type in Banner::add() matches a defined type in config/banner.php. Defaults to info if invalid.

4. Migration Conflicts If manually editing the banners table, reset migrations:

   php artisan migrate:fresh
   

5. Filament V5 Compatibility

   • Ensure Filament V5 is installed (filament/filament:^5.0) to avoid version conflicts.
   • If using both Filament notifications and this package, test for styling conflicts in your theme.

Debugging Tips

1. Inspect Registered Banners Dump all banners in Tinker:

   php artisan tinker
   >>> \Kenepa\Banner\Facades\Banner::all();
   

2. Check Storage Driver Verify config/banner.php driver setting (default: session). For cache, ensure Banner::clear() is called on cache flush.

3. Blade Rendering Issues Ensure @banner('key') is placed after Banner::add() in the request lifecycle (e.g., not in a layout file before the controller runs).

4. French Translation Debugging If translations aren’t loading, verify:

   • The lang/vendor/kenepa/banner/fr.json file exists (published via vendor:publish).
   • The app.php locale is set to fr or the correct locale is being overridden.

Extension Points

1. Custom Blade Directives Extend @banner with custom logic:

   Blade::directive('customBanner', function ($key) {
       return "<?php if (\Kenepa\Banner\Facades\Banner::exists($key)): ?>
           <div class=\"custom-banner\">...</div>
       <?php endif; ?>";
   });
   

2. Event Listeners Trigger actions on banner events (e.g., BannerCreated):

   Banner::add('welcome', [...], function () {
       // Post-add logic (e.g., analytics)
   });
   

3. Filament V5 Customization Override Filament’s default notification styles to align with this package’s banners:

   // In a Filament resource or page
   use Kenepa\Banner\Facades\Banner;
   
   public static function getPages(): array
   {
       return [
           // ...
       ];
   }
   
   public function mount()
   {
       if (Banner::exists('filament_warning')) {
           $this->notify('warning', Banner::get('filament_warning')->message);
       }
   }