Vcookiebar Laravel Package

Getting Started

• Install with composer require voodflow/voodbuilder-cookiebar. The package is pre-1.0 (0.2.x), so pin an explicit version in composer.json rather than using ^0.2.
• Publish the package assets before touching anything else: php artisan vendor:publish --provider="Voodflow\VoodbuilderCookiebar\CookiebarServiceProvider". Run php artisan vendor:publish with no arguments once to see the exact tags offered (config, views, translations, migrations) — the README is the source of truth for tag names, and they can differ between minor releases.
• Start with config/cookiebar.php. This is where categories (typically necessary, analytics, marketing), cookie name/lifetime, banner text, and the accept/reject/settings behavior are defined. Get the category list right first; everything else (script gating, consent storage, UI) keys off it.
• Register the package middleware in the web group in app/Http/Kernel.php (or bootstrap/app.php on Laravel 11+) if you want the bar injected automatically. The alternative is to include the Blade component manually in your layout just before </body> — pick one, not both.
• First real use case: a necessary-only banner that records a consent decision and exposes a settings panel for optional categories. Render the component in resources/views/layouts/app.blade.php, accept the defaults, then verify a cookie is written on click before customizing anything.

Implementation Patterns

• Layout component vs. middleware injection. The component approach is easier to reason about and plays nicely with Livewire/Inertia layouts; middleware injection is convenient for classic server-rendered apps but fights with full-page caches. Most teams standardize on the component and skip the middleware.
• Server-side gating is the reliable gate. Use the package's helper (e.g. cookiebar()->allows('analytics')) around analytics/marketing script tags in Blade. Client-side gating via data-cookiebar-category attributes is fine for convenience but should not be the only enforcement for anything privacy-relevant.
• Consent versioning. Store a consent "version" alongside the accepted categories so that adding a new category later re-prompts users. This is not something the package necessarily does for you — build it into the config or a small wrapper.
• Persist consent for audit. If the package ships a migration/model, publish and run it. If not, wrap the accept/reject event in a listener and write to your own consents table (user id or anonymous uuid, categories, version, IP hash, timestamp). Cookie-only consent is hard to defend in an audit.
• Gate third-party embeds. The common integration point is a Blade partial that swaps a YouTube iframe / GTM snippet for a placeholder until the relevant category is allowed. Keep that partial in your app, not in the vendor views, so upgrades don't clobber it.
• Translations. Publish the translation files and key your banner copy off Laravel's locale. Cookie consent text is a legal surface — expect it to be rewritten by legal, not by you.
• Testing. Set the package config to disable rendering in phpunit.xml (or via a cookiebar.enabled=false env) and drive the accept/reject flow with $this->withCookie(...) / $this->withUnencryptedCookie(...) to assert gated content appears. Asserting on the rendered banner itself is brittle; assert on the helper's return values.
• Environment toggles. Keep the banner off in local/CI, on in staging/prod, and configure a cookiebar.debug flag if available so you can see which category decisions were resolved without reading cookies by hand.

Gotchas and Tips

• 0.2.7 shipped with an empty changelog (only a compare link). Review the diff on GitHub before upgrading from 0.2.6; with no documented changes you cannot assume it is a pure bugfix. Given the pre-1.0 version, treat any 0.x bump as potentially breaking.
• Config cache. After publishing or editing config/cookiebar.php, run php artisan config:clear (and config:cache in deploy). A stale cached config is the most common cause of "my category changes did nothing."
• necessary must always be on. Several cookie-bar packages let you accidentally toggle it off in config; if you do, the banner will re-prompt forever or, worse, block session/auth cookies. Guard that category in config and in your settings UI.
• Middleware ordering. If you inject via middleware, register it after StartSession and after any response-caching middleware. Putting it before a cache layer means the banner gets cached into responses for users who already consented, or cached out for users who haven't.
• Full-page caches and CDNs. Injected consent state is per-user; make sure the banner markup is not being cached at the edge. Either exclude the banner from cached HTML or render it client-side and hydrate from a cookie.
• Cookie flags. Check SameSite, Secure, and HttpOnly settings in config. HttpOnly is usually wrong here if you need JS to read consent for client-side gating; Secure should be on in production. Cookie name changes silently invalidate existing consents — version the name.
• Blade view overrides. Publish the views and commit them if you need custom markup. If you rely on vendor/ overrides instead, your customizations disappear on composer update with no warning.
• Debugging checklist when the bar doesn't appear or gating misbehaves: (1) is the component/middleware actually in the layout, (2) is cookiebar.enabled true for the env, (3) is config cached, (4) is the consent cookie present and correctly named, (5) does the helper see the same category keys you configured, (6) is a response cache serving stale HTML.
• Extension points to prefer: published config, published views, and the package's consent event/listener (if exposed) for persistence. Avoid subclassing vendor classes — at 0.2.x those are the most likely to move.