Statamic Cookie Dialog Laravel Package

Getting Started

• Install: composer require emplify-software/statamic-cookie-dialog. Statamic auto-discovers the addon service provider; no manual config/app.php registration needed.
• Publish assets first: run php artisan vendor:publish and select the package's config and view tags. You want two things on disk:
  • config/statamic/cookie-dialog.php — cookie name/lifetime, consent categories, default state, per-site overrides.
  • resources/views/vendor/statamic-cookie-dialog/ — the dialog markup you'll actually restyle.
• Where to look first: the published config file. It is the whole contract of the addon — categories, texts, cookie lifetime, and (as of v3.0.4) multi-site scoping. Read it top to bottom before touching views.
• Wire it into the layout, once. Include the addon's tag/partial immediately before </body> in resources/views/layout.antlers.html so every page gets the dialog without per-template work. Avoid putting it inside a page-level partial that some templates skip.
• First use case: essential-only default with an explicit "Accept all" / "Reject optional" pair, storing the accepted category list in a JSON cookie, then gating third-party scripts on that cookie. Ship that before you attempt granular per-vendor toggles.

Implementation Patterns

Category-driven script gating. Model consent as categories (necessary, analytics, marketing) rather than a boolean. Gate scripts with a non-executing type and swap it on consent:

<script type="text/plain" data-consent="analytics" data-src="https://www.googletagmanager.com/gtag/js?id=G-XXXX"></script>

document.addEventListener('cookie-dialog:accepted', (e) => {
  const granted = e.detail?.categories ?? [];
  document.querySelectorAll('script[data-consent]').forEach((el) => {
    if (granted.includes(el.dataset.consent)) {
      const s = document.createElement('script');
      s.src = el.dataset.src;
      s.async = true;
      document.head.appendChild(s);
    }
  });
});

Check the addon's actual event name in the published JS before wiring this — the pattern is stable, the event string is not.

Multi-site (new in v3.0.4). This is the release that matters. Treat site context as a first-class input:

• Give each site its own consent cookie name (e.g. suffix with the site handle) unless you have a deliberate legal reason to share consent across sites.
• Override texts/translations per site rather than relying on a single set of strings — cookie law wording differs by jurisdiction, and locales differ by site.
• In Antlers, resolve site-aware content with {{ site:handle }} / Site::current() when you need to vary the dialog's intro copy or links to a privacy policy that lives per-site.
• Verify the fallback: confirm what a site with no explicit override inherits (root config vs. hardcoded defaults) instead of assuming.

Consent before tags fire. If you use GTM or Google Consent Mode, set defaults to denied in <head> before the container loads, then call gtag('consent', 'update', …) from the addon's accept event. A dialog that renders the UI correctly but lets GTM fire on page load is the most common failure mode of packages like this.

Re-openable preferences. Cookie banners are not one-shot. Expose a footer link ("Cookie settings") that re-opens the dialog so users can withdraw consent — required under GDPR and an easy thing to forget.

Static caching. With Statamic's static cache enabled, the dialog HTML is baked into the page and the cookie is client-side only. That's fine, but: warm each site's URLs separately, and make sure any server-rendered "you have already consented" state isn't cached into the page for everyone.

Gotchas and Tips

• Cookie collision across sites is the headline risk in v3.0.4. If two sites share a domain (subdirectories) or set the cookie on a parent domain (.example.com), a consent granted on site A can read as granted on site B. Namespace the cookie per site handle, and decide explicitly whether that's what you want — for different jurisdictions it usually isn't.
• Check whether the config is keyed by site handle or expects per-site files. v3.0.4's multi-site support may be implemented as an array keyed by site handle, or as separate config files. Read the published config after upgrading; guessing here produces silent fallbacks.
• config:cache bites you. Statamic/Laravel config is cached in production. After editing cookie-dialog.php, run php artisan config:clear (or config:cache) or your override simply won't apply, and you'll spend an hour debugging the wrong layer.
• Inline scripts still execute. Wrapping content in type="text/plain" only stops external script loading when the tag is created dynamically. Any already-inlined analytics snippet will run regardless — move it to the gated pattern.
• Cached locale in translations. If strings go through __() and you use full-page caching without site-aware cache keys, one site's language can be served to another. Confirm the static cache path includes the site/domain.
• Debugging checklist: inspect the consent cookie in DevTools (name, domain, path, expiry); clear it and reload; check that the dialog renders in the raw HTML before JS runs; then check the accept event fires and gated scripts appear in the network tab.
• Extension points: publish and override views rather than editing vendor files; use config to add categories; use the accept/decline events to hook your own tag manager. If the addon doesn't expose an event you need, that's the right place to file an issue.
• Version note: v3.0.4 is a single change (multi-site support, PR #22) with no deprecations or breaking changes signalled. Pin ^3.0 and test the upgrade on a multi-site install specifically — that's the code path that changed.