Client Bundle Laravel Package

Getting Started

• Confirm the target framework first. setono/client-bundle is a Symfony bundle, not a Laravel package. There is no Laravel service provider, facade, or config/client.php. In a pure Laravel app you will not composer require this into your HTTP stack; you will either (a) run it inside a Symfony service/kernel in a hybrid setup, or (b) read the rewritten README and port the consent-gated cookie pattern into Laravel middleware, queued cookies, and events.
• Upgrade is trivial. v1.2.0 has no public API or runtime changes, so composer require setono/client-bundle:^1.2 is a drop-in from v1.1.0. Run the test suite, then ship.
• Start with the README, not the source. v1.2.0 rewrote it with a requirements table, Flex/manual install steps, a "How it works" section, consent handling via PreStoreCookieEvent, extension points, and a contributing guide. That is now the fastest path to understanding the lifecycle.
• First use case: consent-aware storage of a client identifier in a cookie. The bundle gives you a storage service plus an event that fires before the cookie is written, so you can block or mutate storage until consent exists.
• Minimum viable check: install, register the bundle (Symfony bundles.php), configure cookie attributes, dispatch/consume PreStoreCookieEvent in a listener, and assert the cookie is absent before consent and present after.

Implementation Patterns

• Gate writes on consent, not reads. Attach a listener/subscriber to PreStoreCookieEvent and only allow the store to proceed once your consent record (CMP, cookie banner, server-side consent log) says yes. Treat the event as a veto point, not a post-write notification.
• Never touch $_COOKIE or setcookie() directly. Go through the bundle's client/storage service so cookie name, lifetime, Secure, HttpOnly, and SameSite stay consistent and are configured in one place.
• Use decoration for custom storage. If you need a different backing store (session, database, signed cookie), decorate the existing storage service rather than replacing it, so the event flow and defaults remain intact.
• Port the pattern to Laravel rather than the package. A close equivalent is: a ClientCookieMiddleware that reads a consent flag, a PendingCookieJar-style service, and an event/listener pair mirroring PreStoreCookieEvent. Use Cookie::queue() so headers are not written too early.
• Reuse the release's CI posture. The repo moved to PHPStan at level: max, Rector 2, ECS, composer-dependency-analyser, and Infection with 100% MSI. Copy the PHPStan and Infection setup into your own package/app if you maintain shared cookie or consent code.
• Test the consent boundary explicitly. Unit-test the listener (denied, granted, revoked) and feature-test the response headers. The bundle's own 100% MSI does not cover your consent rules.

Gotchas and Tips

• Framework mismatch is the big one. Do not assume Laravel auto-discovery. In a Laravel-only codebase, treat this as a reference implementation and a source of design patterns, not a runtime dependency.
• Tooling churn can affect contributors, not consumers. The Psalm → PHPStan migration, drop of setono/code-quality-pack in favour of pinned tools, and addition of Infection are dev-dependency changes. Runtime consumers on PHP 8.1 are unaffected, but forks and contributor environments will need composer update and possibly new local PHP extensions.
• PHP 8.1 remains the floor. Confirm your CI matrix still includes 8.1 if you contribute; the release explicitly preserves it.
• Event timing matters. PreStoreCookieEvent runs before persistence. Mutating a response or cookie after headers are sent will fail silently or throw depending on your stack. Resolve consent before the response is prepared.
• Cookie attributes are a compliance surface. SameSite, Secure, domain, and lifetime should be config-driven. A cookie that works locally over HTTP can disappear in production behind HTTPS/SameSite=Lax assumptions.
• Docs were rewritten, so old links may rot. README anchors and section names changed in v1.2.0. Update internal onboarding docs and bookmarks that pointed at the v1.1.0 README.
• Debugging checklist: confirm bundle registration, confirm the event dispatcher is wired, dump listeners for PreStoreCookieEvent, and inspect the response's Set-Cookie header rather than $_COOKIE (which only reflects the next request).
• Extension points are the stable contract. Prefer listeners, decorators, and configuration over subclassing internals; the release notes emphasise extension points in the README, and those are the parts intended to survive future minor releases.