Clarity Laravel Laravel Package

Getting Started

• Install: composer require abr4xas/clarity-laravel. v3 is a major bump driven by orchestra/testbench ^11.0 in CI, which tracks Laravel 13 — confirm your app's Laravel/PHP constraint with composer why-not abr4xas/clarity-laravel ^3.0 before upgrading. Apps on Laravel 11/12 should stay on v2 unless the constraint matrix says otherwise.
• Publish config: php artisan vendor:publish --tag=clarity (list tags with php artisan vendor:publish if the tag name differs). You get config/clarity.php; set the Clarity Project ID (Clarity dashboard → Settings → Setup → Install manually) and the enable flag.
• Where to look first: config/clarity.php, then the service provider to see whether the snippet is injected globally, via middleware, or through a Blade directive. That determines everything downstream (consent, multi-tenant, CSP).
• First use case: put the ID in .env (CLARITY_ID=), reference it as env('CLARITY_ID') in the config, disable injection in local/testing, then load any page and confirm the clarity.ms/tag/... script is in view-source. Then check the Clarity dashboard for a live session.

Implementation Patterns

• Env-driven, never hardcoded. One config key, one .env entry per environment; production gets the real ID, staging a separate project (or disabled), local/testing disabled.
• Environment gating. Wrap the enable flag in app()->isProduction() (or an explicit allowlist) so preview deployments and CI don't pollute your analytics with bot traffic.
• Injection point matters. If the package offers both a global injector and a Blade directive, prefer the directive inside your layout partial when you have multiple layouts (public vs admin) and want per-layout control; prefer the global path when you want zero template edits. Do not use both.
• Consent / GDPR. Disable auto-injection and render the snippet from your own Blade component gated on a consent cookie, or wrap it behind a consent middleware. Session recording without consent is the classic compliance failure here.
• SPA / Inertia / Livewire. The tag only needs to load once — put it in the root Blade template (app.blade.php). Verify that client-side navigation doesn't re-inject the tag on every route change.
• Multi-tenant. A static config value won't work when each tenant has its own Clarity project. Resolve the ID per request (tenant model → view composer or a small custom renderer) and keep the package's global injection off.
• v3 buffering. The command was refactored to use native output buffering, so injection now happens at the PHP output layer rather than through response mutation. Remove any hand-rolled injection code you added around v2 — it will now double up.
• Testing. Add CLARITY_ID to phpunit.xml as empty/disabled and assert presence in a single feature test (assertSee('clarity.ms', false)) so a config or provider regression fails loudly.

Gotchas and Tips

• Config cache is the #1 "it stopped working". After editing config/clarity.php or .env, run php artisan config:clear (and re-cache on deploy). A stale cached config is silent.
• Upgrading from v2: re-publish the config and diff it — major versions can change keys. Then run php artisan list clarity and confirm the refactored command's signature before wiring it into deploy scripts; arguments/options may have moved.
• Octane / RoadRunner: native buffering interacts with the worker lifecycle. Restart workers after deploy and verify the tag on a warm worker, not just the first request.
• Streamed and binary responses: check a download route and any response()->stream() endpoint — you don't want an analytics snippet appended to a file payload.
• CSP: whitelist https://www.clarity.ms, https://scripts.clarity.ms and Clarity's connect endpoints. Otherwise the tag loads, blocks silently, and you get no sessions with no error in the console beyond a CSP violation.
• Ad blockers: an empty network tab locally is usually uBlock, not a broken package. Test in a clean profile or verify server-side rendering of the tag instead.
• Debug ladder: config value non-empty → package discovered (php artisan about) → tag in view-source → requests to clarity.ms in the network tab → session visible in the dashboard (reporting lags by minutes, longer for aggregated views).
• Duplicate tags: if anyone pasted the manual snippet into the layout, you'll double-count pageviews. Pick one mechanism and delete the other.
• Extension points: published config and views are the supported surface. If neither fits your consent or multi-tenant story, disable auto-injection and ship a five-line Blade partial rather than fighting the internals — that partial will survive the next major bump.