Filament Cookie Consent Laravel Package

Getting Started

The package is a thin Filament wrapper around jeffersongoncalves/laravel-cookie-consent. It does two things: registers render hooks that inject the consent script into <head> and the banner markup at the end of <body> on every panel page, and ships a Filament settings page (backed by spatie/laravel-settings) so marketing/legal can change copy and colours without a deploy.

1. Pick the right major for your Filament version. This is the single most common way to lose an hour:

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

2. Publish both sets of migrations — in this order. The settings table comes from Spatie, not from this package, so a bare php artisan migrate after install leaves you with a settings page that throws "table not found".

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 the panel provider(s) that should show the banner:

use JeffersonGoncalves\Filament\CookieConsent\CookieConsentPlugin;

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

4. Look here first: the Cookie Consent Settings page under the Settings navigation group. That page is the entire configuration surface — there is no config/cookie-consent.php to edit. It is grouped into Assets (CSS/JS URLs), Content (header, message, button labels, privacy policy URL + link target, cookie policy text), Popup/Button/Highlight colours, Layout (position, theme), and — since 3.7.0 — Compliance.

5. First use case: open the settings page, set the Privacy Policy URL, switch Compliance type from info to opt-in (this is what reveals the Allow/Decline buttons), save, then load your panel in a private window. You should see the banner bottom-right (or wherever you set it) with your brand colours, and the consent payload in the browser. Private window matters — the consent flag is stored client-side, so a normal window that already accepted will show nothing and look broken.

Implementation Patterns

Treat the settings as data, not config. Everything lives in the database via Spatie Settings. That means your deploy pipeline needs the migrations run and the settings cache cleared (see Gotchas). A typical deploy step:

php artisan migrate --force
php artisan optimize:clear

Disable the page for non-admin panels. If you register the plugin on a customer-facing panel just for the banner, don't hand them a settings page. Same plugin, one flag:

CookieConsentPlugin::make()->settingsPage(false),

This is the pattern I'd default to: one "admin" panel owns the settings page, every other panel registers the plugin with settingsPage(false). Because settings are global, the values edited in the admin panel automatically apply to the others — you don't re-enter copy per panel.

Seed content programmatically for staging/CI. Manually clicking through 15 colour fields in every environment is waste. Resolve the settings class from the base package and fill it in a seeder or a one-off tinker session:

// find the exact class with: grep -r "class .*Settings" vendor/jeffersongoncalves/laravel-cookie-consent/src
$settings = app(\JeffersonGoncalves\Laravel\CookieConsent\Settings\CookieConsentSettings::class);
$settings->privacy_policy_url = 'https://example.com/privacy';
$settings->compliance_type    = 'opt-in';
$settings->position           = 'bottom-right';
$settings->save();

Wrap that in a seeder guarded by if (app()->environment('local', 'staging')) so you never overwrite legal-approved consent copy in production.

Google Consent Mode v2. The 3.7.0 Compliance section adds an opt-in/opt-out choice (which is what renders the Allow/Decline buttons) and a Consent Mode toggle that pushes consent default / consent update onto the dataLayer. The README is explicit that the cookie consent head hook renders before filament-gtm / filament-gtag — that ordering is what makes Consent Mode work at all. If you add your own analytics plugin, register it after this one in the ->plugins([...]) array and verify in DevTools that your tag sees gtag('consent', 'default', …) before it fires.

Consent-gated functionality. The banner is client-side only; the package does not give you a server-side "did this user consent" API. For conditionally loading a chat widget or a tracking script, read the consent state in Blade/Alpine from the cookie/dataLayer the JS sets, and ship the gated script in a @push('scripts') block gated on that. Don't assume the package will block anything for you.

Brand alignment. Drive everything through the settings page rather than committing CSS overrides: popup background/text/link, button background/border/text, highlight background/border/text, plus position (top-left/top-right/bottom-left/bottom-right) and theme. That keeps the legal team self-serving and stops your repo accumulating !important rules against markup you don't control.

Multi-language. Labels ship in 19 languages (English and pt-BR originally, expanded later). For a per-locale consent message, either rely on the translation keys or set the content fields per environment. Note that content fields are single-value — you get one message string per environment, so multi-locale marketing copy needs separate panels/environments or a small customisation.

Pin and smoke-test. Nine stars and zero dependents means you are the QA. Pin the minor (^3.7), and add one Pest test that boots the panel and asserts the render hook output contains your consent marker — that catches the Filament-minor breakage pattern this package has already hit twice (the PageConfiguration signature change in 3.2.1/2.3.1).

Gotchas and Tips

Version skew is silent until it's a 500. 3.2.1/2.3.1 bumped minimums to Filament ^5.3 / ^4.8 because Page::routes() gained a PageConfiguration parameter. If you're mid-upgrade on Filament, install this package after the Filament upgrade, not before, or the settings page route registration explodes.

The compliance toggle needs a migration you may have already "done". 3.7.0's Compliance section depends on laravel-cookie-consent ^4.2, which adds new settings columns. Updating the composer package is not enough — re-publish/re-run migrations:

composer update jeffersongoncalves/filament-cookie-consent
php artisan vendor:publish --tag=cookie-consent-settings-migrations   # may need --force if already published
php artisan migrate

If you use --force on the publish, diff the file before running — you can clobber an edited migration in a repo that has already shipped.

Don't publish the Spatie migrations twice. On an existing app the Spatie settings migration is almost certainly present. vendor:publish will ask before overwriting; say no. The failure mode of a duplicate is a settings table already exists error on deploy.

Settings cache, not config cache. Spatie caches settings. After editing values in the panel you normally see them immediately, but if you've cached settings in a custom settings class or run php artisan config:cache, stale values survive. When a colour or URL change "doesn't take", run php artisan optimize:clear before you go debugging the render hooks.

The banner won't appear outside the panel. This is Filament-only by design — it registers Filament render hooks. Your public marketing site, login pages from Breeze/Fortify, and error pages get nothing. For those, install the base jeffersongoncalves/laravel-cookie-consent package directly (it's already in your tree as a dependency) and include its blade partial, or extract a shared layout. Also check: if you use Filament's own login/registration pages, those are panel pages and will show the banner — sometimes you want to suppress it on auth screens via a render-hook condition rather than showing legal copy to a user who can't proceed.

Multiple panels = multiple banners and possibly multiple settings pages. Register on two panels without settingsPage(false) on one, and you get two nav entries editing the same underlying settings row. Confusing but not broken — the values are shared. Be deliberate.

Debugging "banner not rendering": (1) is the plugin actually in that panel's plugins()? (2) view-source and search <head> for the CSS/JS asset URLs — if the hook fired, they're there; (3) are the asset URLs set to reachable, correct-CDN paths (a 404 CDN URL gives you an unstyled/unscripted banner or nothing); (4) private window — prior consent suppresses it; (5) check your CSP: external asset URLs plus inline dataLayer pushes are a common Content-Security-Policy casualty on hardened panels.

Layout surprises are usually the theme/position fields, not CSS. top-left etc. are stored strings the template maps to classes. If the banner jumps after a save, confirm the setting persisted (check the DB row) rather than chasing cached views.

Extension points are limited, so plan around them. The published surface is the plugin's make() / settingsPage(bool) and the settings fields. For anything else — different markup, a preferences centre, granular category toggles beyond info/opt-in/opt-out — you're subclassing the plugin or replacing the base package's blade views, both of which are on you across upgrades. Keep customisations in a small wrapper class so the next package bump is a one-file diff, and re-read the CHANGELOG before every minor: this maintainer ships breaking minimum-version bumps inside patch releases.