Client Id Laravel Package

Getting Started

• composer require setono/client-id. There is no Laravel service provider or facade — this is a framework-agnostic library (the Symfony integration lives in a separate bundle), so budget ~15–30 minutes to wire it into the container yourself.
• Read these three things first, in order:
  1. The ClientId value object (what you actually pass around).
  2. The provider interface and its cookie-backed implementation (this is where the read/write logic lives).
  3. The UUID generator (the default implementation; swappable).
• First use case: stamp a stable, opaque client_id cookie on a visitor's first request, then read it back on every subsequent request. That ID becomes the join key between your browser-side pixel (Meta, TikTok, GA4) and your server-side events (Conversions API, Events API, Measurement Protocol). Without a shared key, server events can't be deduplicated against browser events and your attribution gets noisy.
• Minimal wiring:
  • Bind the generator + provider as singletons in a ClientIdServiceProvider.
  • Add a small middleware (or a terminate hook) that ensures the cookie exists on the outgoing response.

Implementation Patterns

• Middleware-based stamping. Register a global or web-group middleware that resolves the client ID at request start and, if absent, writes a fresh one onto the response. Keep the write in terminate() or on the response object so you don't clobber it on redirects.
• Resolve once, inject everywhere. Bind ClientId as a scoped/singleton instance resolved from the request. Then any controller, job, or listener can type-hint it rather than re-parsing the cookie. This keeps conversion-tracking code clean: SendPurchaseEvent::dispatch($order, $clientId).
• Pair with the browser pixel. The whole point is matching IDs. Have your front-end pixel send the same cookie value as external_id / client_id in its payload. Server-side, read the cookie via the provider and send the identical value. Deduplication then works on (event_name, event_id, client_id).
• Queue-safe. If you dispatch conversion events to a queue, capture the ClientId value before dispatch — queues have no request/cookie context, and the provider will return null in a worker.
• Testing. withCookie('client_id', $uuid) (or withUnencryptedCookie if you've excluded it from encryption) in feature tests, and assert the cookie is set on first-hit responses. Test the "cookie already present" path separately — it's the branch that silently breaks.
• Behind a proxy / CDN. If you're on Cloudflare or similar, make sure the cookie isn't stripped or cached. Client ID generation should be on uncacheable responses.

Gotchas and Tips

• v0.2.2 drops Symfony 4 support. For a modern Laravel app this is a non-event, but it is a dependency floor bump. If you're pinned to an older Laravel (8.x on Symfony 5 components is fine; anything that drags in symfony/http-foundation 4.x is not), composer will refuse the upgrade. Run composer why-not setono/client-id 0.2.2 before assuming it's safe. Treat it as a maintenance release otherwise — no API changes for a Laravel consumer.
• Laravel encrypts cookies by default. If your JavaScript needs to read the client ID, you must add the cookie name to App\Http\Middleware\EncryptCookies::$except. If you forget, the browser sees an encrypted blob and your pixel/server matching silently fails — no error, just 0% match rate. This is the single most common integration bug.
• HttpOnly is a deliberate trade-off. Server-only matching can keep it HttpOnly; browser matching requires it readable. Decide early; changing it later rotates every visitor's ID.
• Consent gating is on you. The package sets a cookie unconditionally. If you're under GDPR/ePrivacy, wrap the "ensure client ID exists" step behind your consent check, or generate a session-scoped ID until consent is given.
• Middleware order matters. Run the client-ID middleware before anything that reads the cookie, and after EncryptCookies so the exclusion applies. Debugging tip: if the ID rotates on every request, you're either setting the cookie on a cached response, or the encryption exclusion isn't in place.
• Extension points are the reason to use this over a one-liner. Swap the UUID generator for a different ID format (e.g., ULID), or replace the cookie provider with a session/DB-backed store if you need long-lived IDs that survive cookie clearing. The interfaces are small and designed for this.
• No config to publish, no artisan command, no docs generation. Everything is constructor wiring. Keep your service provider thin and put the cookie name/TTL in a config file so ops can change it without a deploy of business logic.