Filament Cookie Consent Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require jeffersongoncalves/filament-cookie-consent:^3.2
   

2. Publish migrations (for database-backed settings):

   php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="migrations"
   php artisan vendor:publish --tag=cookie-consent-settings-migrations
   php artisan migrate
   

3. Register the plugin in your PanelProvider:

   use JeffersonGoncalves\Filament\CookieConsent\CookieConsentPlugin;
   
   public function panel(Panel $panel): Panel {
       return $panel->plugins([
           CookieConsentPlugin::make(),
       ]);
   }
   

First Use Case

• Enable cookie consent for your Filament admin panel immediately.
• Configure via the admin UI: Navigate to the new "Cookie Consent Settings" page under "Settings" to customize:
  • Banner text, colors, and position.
  • Privacy policy links.
  • Cookie categories (e.g., analytics, marketing).

Implementation Patterns

Workflow Integration

1. Admin Configuration:

   • Use the Filament settings page to define:
     • Content: Header, message, button labels, and privacy policy URLs.
     • Styling: Colors for banners, buttons, and highlights.
     • Layout: Position (top/bottom), theme (light/dark), and cookie categories.
   • Example:

     CookieConsentPlugin::make()
         ->settingsPage(true) // Default: true
         ->group('Legal')      // Customize navigation group
     

2. Conditional Rendering:

   • The package automatically injects the cookie consent banner into Filament pages via render hooks.
   • No manual Blade template inclusion is required.

3. Multi-Language Support:

   • Translate content (e.g., "Accept All," "Privacy Policy") using Filament’s built-in localization or custom language files.

4. Cookie Category Management:

   • Define categories (e.g., analytics, marketing) in the settings page and map them to Laravel’s cookie groups:

     // In a service provider or config file
     'cookie_consent' => [
         'categories' => [
             'analytics' => ['google_analytics', 'matomo'],
             'marketing' => ['facebook_pixel'],
         ],
     ]
     

5. Custom Scripts/Styles:

   • Override default assets (e.g., CSS/JS) by publishing the package’s views:

     php artisan vendor:publish --tag=cookie-consent-views
     

   • Extend the banner template in resources/views/vendor/cookie-consent/banner.blade.php.

Common Use Cases

• GDPR/CCPA Compliance: Enable cookie consent for all Filament pages with minimal setup.
• A/B Testing: Use the settings page to test different banner designs without code changes.
• Third-Party Integrations: Link cookie categories to services like Google Analytics or Hotjar via the admin panel.

Gotchas and Tips

Pitfalls

1. Filament Version Mismatch:

   • v3.x requires Filament 5.3+. Downgrade if using an older version:

     composer require jeffersongoncalves/filament-cookie-consent:^2.3
     

   • Check the compatibility table in the README.

2. Missing Migrations:

   • Forgetting to run php artisan migrate after publishing settings migrations will break the settings page.
   • Fix: Run migrations manually or use a seed class to auto-migrate.

3. Render Hook Conflicts:

   • If the banner doesn’t appear, ensure no other package is overriding Filament’s body.end or head.end hooks.
   • Debug: Temporarily disable other plugins to isolate the issue.

4. Cookie Persistence:

   • The package uses Laravel’s native cookie system. Ensure your APP_URL and session driver are configured correctly in .env.

Debugging Tips

• Check Settings:
  • Verify settings are saved by inspecting the settings table or using Tinker:

    php artisan tinker
    >>> \Spatie\LaravelSettings\Setting::get('cookie_consent');
    

• Clear Cache:
  • After publishing views or config, clear Filament’s cache:

    php artisan filament:cache:clear
    

• Log Cookie Consent Events:
  • Extend the package to log consent actions (e.g., user clicks "Accept"):

    // In a service provider
    event(new \JeffersonGoncalves\LaravelCookieConsent\Events\ConsentGiven($categories));
    

Extension Points

1. Custom Consent Logic:

   • Override the consent check middleware by publishing the package’s middleware:

     php artisan vendor:publish --tag=cookie-consent-middleware
     

   • Extend App\Http\Middleware\CheckCookieConsent to add custom logic (e.g., redirect non-consenting users).

2. Dynamic Content:

   • Fetch banner content dynamically by overriding the settings retrieval:

     // In a service provider
     \Spatie\LaravelSettings\Setting::macro('cookieConsent', function () {
         return collect([
             'header' => 'Custom Header',
             // ... other settings
         ]);
     });
     

3. Multi-Tenant Support:

   • Use Filament’s tenant middleware to scope cookie consent settings per tenant:

     // In a middleware
     \JeffersonGoncalves\LaravelCookieConsent\Facades\CookieConsent::setTenant($tenantId);
     

4. Testing:

   • Mock the cookie consent banner in tests by overriding the render hook:

     // In a test
     $this->app->make('filament')->registerRenderHook(
         'body.end',
         fn () => '<div data-testid="cookie-banner">Mock Banner</div>'
     );