Consent For Laravel Laravel Package

Getting Started

This is the first assessment for jakub-lipinski/consent-for-laravel, so treat v1.5.0 as the baseline.

Install

composer require "jakub-lipinski/consent-for-laravel:^1.5.0"
php artisan view:clear

Requirements are PHP 8.3+ and Laravel 12–13. There is no database migration, no cookie migration, and no consent reset — existing saved preferences and their original expiry remain valid as long as policy, services, and consent settings are unchanged. That makes v1.5.0 a safe drop-in.

Where to look first

1. The package config (livewire block, ui.locale, services/presets, cookie scopes, audit settings).
2. The published head and banner views, plus the three assets: consent.js, banner.js, consent.css.
3. Only then, the Livewire surface — it is optional and off the critical path.

First use case Render the banner once per shared layout and confirm consent toggles persist across a normal full-page navigation. Once that works, enable livewire.navigation = 'auto' and verify the dialog still behaves correctly under wire:navigate. Leave livewire.enabled = true (the default) unless you specifically need to disable SPA coordination while keeping generic script gating.

If you use Livewire at all, read the dedicated reference in the bundled skill (consent-for-laravel-development), and pull the refreshed guidance with:

php artisan boost:update

Do not reinstall the skill — it is one skill with thirteen references.

Implementation Patterns

Head + banner in every participating shared layout. Keep exactly one head marker and one banner per shared layout. The runtime-context marker (configuration/asset revisions), data-consent-container, matching audit notice, full wire:ignore, presentation key, and locale/context attributes must all be preserved together. If you customize the head or banner, refresh all three published assets at the same time.

Livewire navigation modes. Pick the mode deliberately:

• auto (default) — coordinates SPA visits; falls back to full visits when the runtime is nonce-bearing Livewire 3 or an unknown major.
• reload — full visits only; the safe choice if you do not want to reason about SPA lifecycle.
• enabled = false — disables special navigation/UI coordination only. Fragment discovery and inert-script protection still apply.

Instrumenting navigations. Register the consent:navigated listener once, using the existing guarded helpers:

document.addEventListener('consent:navigated', (e) => {
  const { id, url, title, previousUrl } = e.detail;
  // send a page view — do NOT assume the adapter measures for you
});

The adapter sends no automatic SPA measurements. The event fires once per completed compatible swap; initial load, prefetch, canceled visits, ordinary component morphs, and hash-only changes without a swap emit nothing. Use this to drive virtual page views in your analytics tool.

Language following. Leave ui.locale = null and omit an explicit banner locale to inherit the application's locale. Set and preserve the locale before rendering pages and Livewire updates. Regional fallbacks are automatic: cs-CZ / cs_CZ → Czech, nl-NL / nl_NL / nl_BE → Dutch, unless a more specific dictionary exists. Bundled translations work without publishing; merge custom wording rather than replacing dictionaries, so partial app-owned Dutch dictionaries still inherit the remaining Dutch messages before falling back to English.

Persisting across navigation. @persist is optional. When used, its layout-level wrapper must keep the complete UI and notice outside the Livewire components. A persisted interface whose incoming locale differs from the app/config locale forces a full refresh; for other presentation changes, change the persist key or remount normally.

Dynamic @consent blocks. Use stable explicit IDs. Identical logical blocks and SDKs are deduplicated per document, so explicit IDs are what keep that working under morphs.

CSP. Test your actual policy. Supply matching nonces to the consent components and to Livewire. Livewire 4 needs its CSP-safe build when excluding unsafe-eval; Livewire 3 with nonces uses full visits in auto mode. The initial document's CSP governs SPA destinations, and Livewire's DOMParser may require exact static-style hashes as well as nonces.

Gotchas and Tips

• Do not nest @script / @assets with @consent. This is called out explicitly and is a common way to break script gating.
• Refresh all three assets together. Upgrading consent.js without banner.js and consent.css (or vice versa) will leave the head marker's revision comparison inconsistent, triggering bounded fresh-document recovery on every navigation. Cache-bust external assets and clear compiled Blade/Livewire caches after deploy.
• Invalidate stale page HTML. Cached HTML that predates the new head marker can force recoveries until it expires or is purged.
• Script activation pauses during SPA swaps. Preserved unchanged blocks resume in order after navigation; detached blocks cannot start their remaining scripts. If a third-party SDK "randomly" fails after navigation, check whether its block was detached before it finished.
• Dialog drafts. Ordinary morphs preserve the preferences draft; a real navigation closes the dialog without saving and without returning focus to the departing page. Do not expect focus restoration on SPA transitions.
• Refusal and audit recovery survive Livewire history writes. A delayed audit response retains the notice captured at invocation and cannot revive permission after a newer refusal. You do not need to write ordering guards around this yourself — but do not try to re-introduce an older audit response either.
• Withdrawal still requires a full reload. SPA visits cannot stop running tracker code. Active withdrawal keeps its existing signals, declared-cookie cleanup, and required reload; do not attempt to short-circuit this.
• Do not double-count page views. Review vendor-managed history/SPA settings — especially GA4 enhanced history measurement — before adding a consent:navigated listener. Denied measurements are discarded rather than replayed after acceptance, so a listener that skips a denied visit will not silently backfill it later.
• Long-running workers. Restart them after upgrading, and rebuild config/view/route caches. Older published configs inherit the new defaults (enabled => true, navigation => 'auto') automatically, but cached config will not.
• Upgrade sequence matters. Deploy with composer install after committing Composer files, then clear view, rebuild caches, restart workers, and refresh the published assets and customized head/banner views in the same release. Splitting those steps across deploys is where most of the "why did the banner disappear" reports will come from.
• Keep the UI bootstrap outside the protected container. Moving it inside will break the interaction between script gating and Livewire morphs.