README

Service-based cookie preferences for Laravel, with ready-made banners, a native preferences dialog, and consent-aware script loading. Configure your purposes, add two Blade components, and let visitors accept, refuse, or change their choices.

PHP 8.3+ · Laravel 12-13 · MIT · No frontend framework or npm build required in your application. Database storage is optional.

Documentation · Live preview · Packagist · Releases

What is included

Matching Standard and Compact banners/preferences dialogs, three positions, editable colors and wording, and a reopening button.
English, Polish, German, French, Italian, Spanish, European Portuguese, Czech, and Dutch, plus custom languages with per-key fallback.
Configuration-only light, dark, automatic, and inherited themes, with independent color palettes for both variants.
Five purpose categories, versioned preferences, equal acceptance/refusal retention, and safe defaults without a valid decision.
Optional database audit history with signed copies of the rendered banner and preferences dialog.
Cache-safe Blade script blocks with ordered loading, duplicate prevention, and permission checks before activation.
Optional Livewire 3/4 support for components, navigation, and interface language changes. See Livewire.
GA4, Google Ads, Meta Pixel, Microsoft Clarity, Matomo, and TikTok Pixel presets, including Google Consent Mode v2.
Laravel Boost guidelines and a development skill with focused configuration, integration, and verification references.
Consent withdrawal with declared cookie cleanup and a default reload when optional code is already running.
Keyboard interaction, native modal semantics, responsive layouts, and optional non-blocking contrast diagnostics.

Install

Run these in your existing Laravel application:

composer require jakub-lipinski/consent-for-laravel
php artisan vendor:publish --tag=consent-config

Laravel discovers the provider automatically. All presets are disabled and custom services are empty by default. With no optional purpose configured, only the preferences launcher appears. See installation for requirements, publishing options, and troubleshooting.

Quick start with GA4

Enable the existing GA4 entry in your application's config/consent.php, keeping the other settings and presets:

'ga4' => [
    'enabled' => true,
    'measurement_id' => env('CONSENT_GA4_ID'),
    'send_page_view' => true,
],

This entry belongs inside presets. Set your actual ID in the application's .env:

CONSENT_GA4_ID=G-XXXXXXXXXX

Add the components to your shared Blade layout:

<head>
    <x-consent::head />
</head>
<body>
    {{-- Your application content --}}
    <x-consent::banner />
</body>

The enabled preset registers its purpose and manages loading; no manual service or script wrapper is needed. In the default Google Basic mode, GA4 waits for analytics permission. Remove duplicate tracking snippets, set ui.policy_url to your real policy page, and refresh cached configuration after changes:

php artisan config:clear

During production deployment, use php artisan config:cache after setting environment values and restart long-running workers. Verify pending, refusal, acceptance, and active withdrawal in your application's browser Network panel. Setting an ID alone never enables a preset.

For other presets or your own scripts, follow the complete quick start.

Built-in integrations

Preset	Environment settings	Required permission
`ga4`	`CONSENT_GA4_ID`	Analytics for Basic loading and guarded events
`google_ads`	`CONSENT_GOOGLE_ADS_ID`	Marketing for Basic loading and guarded conversions
`meta_pixel`	`CONSENT_META_PIXEL_ID`	Marketing
`clarity`	`CONSENT_CLARITY_ID`	Analytics; advertising also requires explicit enablement and marketing
`matomo`	`CONSENT_MATOMO_URL`, `CONSENT_MATOMO_SITE_ID`	Analytics
`tiktok_pixel`	`CONSENT_TIKTOK_PIXEL_ID`	Marketing

Google Advanced is an explicit opt-in that allows tags and cookieless pings before permission. Meta, Clarity, Matomo, and TikTok remain strictly gated. The integration guides cover automatic measurements, additional events, account settings, CSP, cookie scopes, and withdrawal, including Matomo and TikTok Pixel.

Your own scripts

@consent('analytics', 'site-analytics')
    <script src="https://your-provider.example/analytics.js"></script>
@endconsent

The URL is a placeholder for your provider. The head component must precede gated code. Blocks render as inert templates and activate in the browser only when permitted, including after a choice on the same page. Registration alone does not load code; requests outside this flow remain your responsibility. See Blade directives.

Customize the interface

Edit the existing ui section in the Laravel-style config, which includes supported values and commented examples:

'variant' => 'compact',
'position' => 'bottom-right',
'theme' => 'auto',
'locale' => null,
'policy_url' => '/cookies',
'validate_contrast' => false,
'colors' => [],
'dark_colors' => [],

Choose standard or compact, and bottom-left, bottom-right, or bottom-center. Set theme to light (default), dark, auto to follow the browser/system preference, or inherit to follow the host page's CSS color-scheme. This is a config setting; no visitor-facing theme button is added. Empty colors and dark_colors inherit independent defaults; override selected keys with six-digit HEX values.

A null locale follows the application. Choose a bundled language or add your own dictionary; missing keys inherit parent-language and English values. A valid locale without a dictionary safely falls back to English. Provide your own policy page.

Contrast diagnostics check both palettes, preserve chosen colors, and never interrupt rendering. Identical palette/issue groups receive one logging attempt every 72 hours through the app's default cache. Cache/logger failures preserve rendering; persistent suppression requires a persistent cache store.

No asset or translation publishing is required to use the defaults. Publish only for customization or external assets. See banner and theme, translations, and CSP and caching.

Existing configs retain the light default; presentation changes preserve saved choices and their expiry. When upgrading customized views and published CSS, update them together using the upgrade guidance.

Optional decision audit log

Enable audit.enabled after publishing and running the optional consent-audit-migrations migration. Explicit acceptance, refusal, preference changes, and withdrawal are stored with server timestamps and an immutable snapshot of the rendered banner/dialog, including custom wording and translations. The default remains disabled.

New optional grants wait for a database receipt; refusal and withdrawal take effect locally immediately. Audit retention is separately configurable. See the audit log guide for installation, pruning, identity, caching, and failure behavior, and v1.3.0 upgrade notes when using published views or assets.

Laravel Boost

The package includes discoverable guidelines and the consent-for-laravel-development skill. In your application, run php artisan boost:install, select this package, and enable guidelines and skills for your agents. Existing Boost installations can add it through php artisan boost:update --discover. See the Boost guide for installation, generated files, reference contents, and custom overrides. Boost is optional and is not a package runtime dependency.

Documentation and updates

The documentation website contains the complete configuration reference and guides:

Configuration, translations, and accessibility.
Browser API, PHP API, and SPA integration.
Persistence, withdrawal, and security.
Upgrading, including earlier VCS installs, and troubleshooting.

Update within your application's allowed Composer constraint, preserve your published customizations, commit the application's lock file, and refresh deployment caches. See the upgrade guide for the v1.5.2 navigation fixes, inherited theme, published resources, and earlier updates. The package's source-oriented guides remain in docs; release history is in CHANGELOG.md.

The browser-readable preference cookie is user-editable and must not be used for authorization or an audit trail. The package provides consent tooling; it does not certify legal compliance or the accessibility of your host website. Describe actual purposes and test the integrated application.

Development

composer install
npm ci --ignore-scripts
composer format
composer check

Node is used only for development tests. See CONTRIBUTING.md for compatibility and native browser verification.

License

MIT.

jakub-lipinski / consent-for-laravel

Package info

Security

Statistics