Cookie Consent Laravel Package

Getting Started

1. Install the package via Composer and let Laravel auto-discover the service provider:

   composer require mrshanebarron/cookie-consent
   

2. Publish the config (and views/translations if you plan to customize) before touching code:

   php artisan vendor:publish --provider="MrShaneBarron\CookieConsent\CookieConsentServiceProvider" --tag=config
   php artisan vendor:publish --provider="MrShaneBarron\CookieConsent\CookieConsentServiceProvider" --tag=views
   php artisan vendor:publish --provider="MrShaneBarron\CookieConsent\CookieConsentServiceProvider" --tag=lang
   

   Since v1.0.2 fixes PascalCase class naming for hyphenated names, double-check the published tags/namespaces against config/cookie-consent.php and the package's composer.json — the exact provider string may differ from the guess above.
3. Look first at config/cookie-consent.php. This is the single source of truth for banner text, button labels, styling, and cookie lifetime. Everything else in the package flows from these keys.
4. First use case — drop the banner into your layout. Add the Blade component to your base template (resources/views/layouts/app.blade.php) so it renders on every page:

   <x-cookie-consent />
   

   If the component alias differs, check the package's Blade service provider registration or the views/components directory after publishing.
5. Gate your first script. Wrap a tracking snippet so it only loads after consent:

   @if (cookie_consent_accepted())
       <script src="https://www.googletagmanager.com/gtag/js?id=G-XXXX"></script>
   @endif
   

   The exact helper name is the one detail most worth verifying against the source — the description promises a "helper/API to gate analytics," but not its signature.

Implementation Patterns

• Layout component pattern (recommended default). Include <x-cookie-consent /> once in your master layout. The package reads its own cookie, so re-rendering on every request is cheap and avoids middleware ordering problems.
• Middleware injection pattern. If you have many layouts or a CMS-driven front end, use the middleware-based injection the package advertises to append the banner to HTML responses. Useful for apps where you can't edit every template, but harder to debug — prefer the component when you control the layout.
• Consent gating in Blade. Wrap third-party scripts inline with the helper:

  @cookieConsent
      <script>/* analytics, pixels, chat widgets */</script>
  @endcookieConsent
  

  (Blade directive name may vary — confirm in the service provider's boot() method.) This keeps gating visible next to the script it protects, which is far easier to audit than a central registry.
• Consent gating server-side. For apps that render tracking IDs from config or set cookies on the server, read the consent state in a middleware or controller and pass a boolean to the view. Don't assume the client-side banner runs before your first render — it doesn't.
• Multi-language sites. Publish the lang files, key the banner copy by locale, and set app.locale normally. Keep legally required text (e.g., "We use cookies to…", "Accept"/"Reject"/"Manage") in translation files rather than config so translators own them.
• Category-based gating (analytics vs. marketing). If the package exposes granular categories, model them as separate config keys and gate each script group independently. If it only exposes accept/reject, don't fake granularity in the UI — it's a compliance liability.
• Staging checklist. Always run composer dump-autoload and php artisan optimize:clear after upgrading, given v1.0.2's class-rename fix.

Gotchas and Tips

• Class name case sensitivity (the v1.0.2 change). The release fixes PHP class naming to PascalCase for hyphenated names. On Linux/case-sensitive filesystems, any hardcoded reference to an old casing will fail with Class not found. Grep your app for the old names before deploying, and confirm the package ships backward-compatible aliases — if it doesn't, treat v1.0.2 as a breaking change.
• Stale Composer classmaps and Laravel caches. After upgrade, composer dump-autoload -o plus php artisan config:clear route:clear view:clear cache:clear resolves the majority of "works locally, broken in prod" reports with this kind of patch release.
• Cookie name/lifetime drift. If you change the cookie name in config after launch, every existing visitor sees the banner again. Keep the key stable, or document the re-prompt. Same for lifetime — shortening it re-prompts sooner, which is a product decision, not a config tweak.
• The banner renders after first paint. Client-side consent means any script that fires on initial page load (GTM, pixels) has already fired unless you gate it explicitly. Gating is on you; the package only records the choice.
• Server-side rendering blind spot. Anything rendered by the server (session-scoped analytics, personalized content) sees no consent cookie on first visit. Design for "unknown consent" as a third state, not just accepted/rejected.
• Extension points to prefer. Config first, published views second, published translations third, and only then consider extending the component class. Forking the views creates upgrade debt on every patch release — and with a single-maintainer, zero-star package, upgrade debt compounds fast.
• Debugging checklist. (1) Is the provider auto-discovered? Check php artisan about / bootstrap/providers.php. (2) Did config publish? php artisan config:show cookie-consent. (3) Is the Blade component registered? php artisan view:clear then inspect the rendered HTML for the banner's root element. (4) Is the cookie actually being set? Inspect in devtools, then confirm the helper reads it.
• Vendor lock risk. Zero stars, one maintainer, patch-level releases. Wrap the helper calls in your own thin service (e.g., App\Support\Consent) so swapping packages later is a one-file change rather than a repo-wide grep.
• Legal review is not optional. "GDPR-compliant" is a package claim, not a certification. Have whoever owns compliance sign off on the banner copy, button parity ("Reject" must be as easy as "Accept"), and which scripts each category gates.