Statamic Oreos Laravel Package

Getting Started

Oreos is a Statamic addon that gives you a cookie-consent banner, configurable cookie/group definitions, and a place to hang consent-gated scripts. v1.3.0 is an additive release: nothing breaks, but two changes (per-cookie details and automatic consent reset on config change) are worth adopting deliberately.

1. Install and publish:

   composer require takepart-media/statamic-oreos
   php artisan vendor:publish --tag=oreos-config
   php artisan vendor:publish --tag=oreos-views
   

2. Look here first: the published config (cookie groups, per-cookie title / description / now details, and the consent-version/hash setting), then the published views under resources/views/vendor/oreos. The addon's README also gained a caching section in this release — read it before you enable Statamic static caching or put a CDN in front of the site.
3. First use case: drop the banner partial into your layout just before </body> (Antlers tag or @include of the published view), define an analytics and a marketing group in config, and render the details text in the cookie list so users can see what each cookie actually does.

Implementation Patterns

Gate scripts on consent, don't just hide the banner. The banner is only half the job — the actual value is wrapping GA/Meta/Hotjar snippets in a consent check (the addon's consent helper in Antlers/Blade, or its JS API for client-side injection). Keep third-party snippets in one partial per group so the consent condition lives in exactly one place.

Use details for the "what and why", keep description short. v1.3.0's details field is the place for retention period, provider, and purpose per cookie. Best pattern: render description in the banner summary and details inside the expanded settings modal, so the first view stays compact on mobile.

Treat the config hash as your cookie-policy version. The new function/config that detects config changes and resets consents means editing your cookie list automatically re-prompts every visitor. That's the correct compliance behaviour — surface it in your privacy-policy changelog ("last updated" should match your deploys that touch config/oreos.php). If you need a manual trigger instead (e.g. only re-prompt on legal review, not on a typo fix), set the version string explicitly rather than relying purely on the auto-hash.

Batch cookie-config edits per deploy. Because of the reset behaviour, three small config tweaks across three deploys equals three re-prompts. Group definition changes into one release.

Plan for caching up front. With static caching or a CDN, the page HTML (including the banner and the config hash it embeds) is served from cache. Follow the new caching README: after changing cookie config, clear the static cache so the new hash actually reaches the browser — otherwise the reset logic never fires for cached visitors.

Gotchas and Tips

• Upgrading from ≤1.2.0: re-publish the views. The "views were not completely published" fix means your existing resources/views/vendor/oreos copy is likely missing files. Diff before running --force so you don't nuke your customisations, and add the details output to any view you've overridden manually — the fix only helps unmodified views.
• Overridden views won't show details until you add it; the config field will exist but render nowhere. Check the modal/cookie-list partial first if the field "does nothing".
• Re-prompting after deploy is not a bug. If users complain the banner came back, look at the config hash/version value first — any change to the cookie definitions (including reordering or a typo fix) can invalidate stored consent.
• Consent is client-side. Clearing browser storage, incognito, or a different device means a fresh prompt. There's no server-side record unless you build one, so don't promise audit logs you don't have.
• details is likely rendered as markup/raw. If editors or translations supply it, sanitise it or restrict it to plain text; with Statamic multisite, put it in translation files or per-site config rather than hard-coding English.
• Static cache invalidation is the usual culprit when "I changed the config but nothing happened" — clear Statamic's static cache and any CDN edge cache, then hard-reload with storage cleared.
• Debugging checklist: banner markup present in the rendered HTML → consent storage key in the browser → config hash value matches the current config → tag is inside <body> and not stripped by a minifier or a consent-blocking extension (some ad blockers hide consent banners, which is a fun support ticket).
• Extension points are the published views and the config; there's no need to fork for styling. Keep custom JS in a separate file keyed off the addon's consent-change event rather than re-binding on every DOM mutation.