Cookie Byte Laravel Package

Getting Started

What this release tells you: v2.0.1 is the first published release after v1.5.4, skipping straight past a major boundary. The release notes contain no changelog body — only a single PR reference from a first-time contributor. That means the v2 upgrade path is undocumented in the notes, and you should treat everything as potentially breaking until you've diffed the source. Start at the v1.5.4...v2.0.1 comparison and the README before touching composer.

Minimal steps:

1. Pin explicitly in composer.json — "dryven/cookie-byte": "^2.0" — and do not let a composer update silently move a v1 app across the major boundary.
2. Publish config and any frontend assets: php artisan vendor:publish --provider="Dryven\CookieByte\CookieByteServiceProvider" (confirm the exact tag names in the README — v2 may have renamed or split tags).
3. Check for a migration: consent/cookie tables are typical for this class of package, and a major bump is the most likely place for a schema change. Run php artisan migrate in a scratch environment first.
4. Clear caches after install — config:clear, view:clear, route:clear — since config key renames are the classic silent breakage between majors.

First use case: the single highest-value thing to get working is the consent gate on non-essential scripts. Wire up one analytics snippet behind the package's consent check, verify it is blocked before interaction and fires after acceptance, and only then roll out to the rest of the tags. That validates config, middleware, asset loading, and the persistence layer in one pass.

Implementation Patterns

Consent-gated rendering (server side). The pattern that ages best is a Blade-level check rather than injecting tags client-side. Wrap each non-essential block in the package's consent directive/helper so the markup is never emitted for a visitor who hasn't accepted. This keeps you honest under GDPR and is trivial to grep during audit.

Centralised tag registry. Rather than scattering conditionals through layouts, keep a config map of category => [scripts] and loop over it. When a category's consent state changes, you re-render. This makes adding a new vendor a config-only change — the main day-to-day win of adopting the package.

Consent-state change listener. Most packages of this shape expose a JS event or callback when preferences are updated. Subscribe once, globally, and use it to (a) inject previously blocked scripts and (b) push the consent state into your tag manager. Do not re-implement the state machine in your own JS.

Middleware for consent-aware responses. If the package ships middleware, register it on the web group rather than per-route. Registering it selectively is the most common cause of "the banner doesn't appear on page X" — an unmatched route silently skips the middleware.

Testing pattern. Drive withSession() or the package's testing helpers to simulate accepted/declined states, then assert on rendered output with assertDontSee('googletagmanager'). Consent behaviour is exactly the kind of thing that regresses silently in a refactor, so a two-line assertion in a feature test pays for itself.

Rollout strategy for v2. Because the changes are undocumented, adopt the strangler pattern: install v2 on one low-traffic internal route, keep v1 in production, and diff the rendered HTML and the cookie jar between the two. Once output is byte-identical apart from expected changes, expand.

Gotchas and Tips

The major bump is the headline, and it's unexplained. A jump from 1.5.4 to 2.0.1 with a changelog that only credits a first-time contributor is a red flag for upgrade risk. Read the commit diff for composer.json (PHP and Laravel version constraints may have moved — check your minimum supported Laravel) and for any renamed config keys, service provider namespace changes, or removed facades. Assume at least one rename.

v2.0.1 implies v2.0.0 shipped and needed a patch. Whatever was fixed in the patch may affect you on first install. Don't pin to 2.0.0; start at 2.0.1.

Config caching is the top debugging trap. php artisan config:cache bakes the published config in. After any package upgrade, in CI and in production deploy scripts, always config:clear before config:cache, otherwise stale v1 keys persist and produce confusing "setting has no effect" symptoms.

Cache-bust consent state deliberately. Consent is usually stored per-session and/or in a cookie. If you use full-page caching (response cache, CDN), the banner state will be served to the wrong users. Either exclude consent-dependent pages from the cache or render the banner shell in JS only. This is a bug that only appears under load in production.

Asset publishing drifts. Published JS/CSS in public/vendor/... does not update when you composer update. If v2 changed the frontend bundle, you must re-publish and commit the assets. Force with --force after backing up any local overrides.

Escape hatch: don't fork to customise. If the banner markup doesn't fit your design, use the published Blade views (override in resources/views/vendor/...) rather than subclassing the service provider. View overrides survive minor upgrades; service provider subclassing breaks on every major.

Debugging checklist when the banner doesn't behave: (1) is middleware actually applied — php artisan route:list -v; (2) is the config published and cached; (3) do you have a stale cookie from a previous version — clear site data; (4) are assets 404ing in the network tab; (5) did the cookie name change between majors (very common, and it resets all existing consents — plan a re-prompt rather than letting it fail silently).

Extension points to look for: a publishable config, overridable Blade views, and any contract/interface for the consent store. If v2 introduced a new interface for the store, implementing it is the clean way to persist consent to the database instead of a cookie — useful if you need an audit trail of who consented to what and when.