Search by

jeffersongoncalves / laravel-cookie-consent

jeffersongoncalves

This Laravel package provides a simple and elegant way to implement cookie consent on your website, ensuring compliance with privacy regulations like GDPR and CCPA. It offers a clean and customizable interface, allowing you to easily manage and display cookie consent banners and preferences.

Package info

github.com/jeffersongoncalves/laravel-cookie-consent

pkg:composer/jeffersongoncalves/laravel-cookie-consent

Statistics

Installs: 19 935

Dependents: 1

Suggesters: 0

Stars: 5

Open Issues: 0

4.7.0 2026-11-18 20:17 UTC

README

Laravel Cookie Consent

Laravel Cookie Consent

Buy Me A Coffee

Latest Version on Packagist GitHub Code Style Action Status Total Downloads

This Laravel package provides a simple and elegant way to implement cookie consent on your website, ensuring compliance with privacy regulations like GDPR and CCPA. It offers a clean and customizable interface, allowing you to easily manage and display cookie consent banners and preferences.

Installation

You can install the package via composer:

composer require jeffersongoncalves/laravel-cookie-consent

Run the migrations to create the settings in the database:

php artisan migrate

Usage

Add head template.

@include('cookie-consent::cookie-consent-head')

Add body template.

@include('cookie-consent::cookie-consent-body')

Publish views (optional).

php artisan vendor:publish --tag=cookie-consent-views

Publish settings migrations (optional).

php artisan vendor:publish --tag=cookie-consent-settings-migrations

Configuration

All settings are stored in the database using spatie/laravel-settings. You can access and modify them at runtime using the CookieConsentSettings class or the cookie_consent_settings() helper.

Accessing settings

use JeffersonGoncalves\CookieConsent\Settings\CookieConsentSettings;

// Via helper
$settings = cookie_consent_settings();

// Via container
$settings = app(CookieConsentSettings::class);

// Read a value
$position = $settings->position;

Updating settings

$settings = cookie_consent_settings();
$settings->position = 'top-right';
$settings->popup_background = '#000000';
$settings->save();

Available settings

Property Type Default
css_url string https://cdn.jsdelivr.net/npm/cookieconsent@3/build/cookieconsent.min.css
js_url string https://cdn.jsdelivr.net/npm/cookieconsent@3/build/cookieconsent.min.js
content_header ?string null (translated)
content_message ?string null (translated)
content_dismiss ?string null (translated)
content_allow ?string null (translated)
content_deny ?string null (translated)
content_link ?string null (translated)
content_href ?string null (hides the "learn more" link)
content_close string ❌
content_target string _blank
content_policy ?string null (translated)
popup_background string #696969
popup_text string #FFFFFF
popup_link string #FFFFFF
button_background string transparent
button_border string #f8e71c
button_text string #f8e71c
highlight_background string #f8e71c
highlight_border string #f8e71c
highlight_text string #000000
position string bottom-left
theme string block
type string info (info, opt-in or opt-out)
consent_mode bool false
mode string banner (banner or categories)
block_scripts bool false
script_categories array [] (script id => category, "" never blocks)
honor_gpc bool false
preferences_css_url string https://cdn.jsdelivr.net/npm/vanilla-cookieconsent@3.1.0/dist/cookieconsent.css
preferences_js_url string https://cdn.jsdelivr.net/npm/vanilla-cookieconsent@3.1.0/dist/cookieconsent.umd.js

Translations

The banner text is translated into the app locale. A content_* text setting left at null renders __('cookie-consent::banner.<key>'); a string value overrides it in every locale.

Shipped locales: ar az cs de en es fa fr he hi id it ja nl pl pt pt_BR pt_PT ru sk tr uk uz zh_CN.

Override or add a locale by publishing the files:

php artisan vendor:publish --tag=cookie-consent-translations

Upgrading: the make_cookie_consent_content_translatable settings migration sets the text settings that still hold the old English defaults to null. Text you customised is kept.

Position

Top Left Top Right
Top Left Top Right
Bottom Left Bottom Right
Bottom Left Bottom Right

Google Consent Mode v2

Google requires Consent Mode v2 for ads and analytics measurement of EEA/UK visitors. Turn it on and pick a compliance type:

$settings = cookie_consent_settings();
$settings->type = 'opt-in';      // banner shows Allow / Decline
$settings->consent_mode = true;
$settings->save();

The head view then pushes gtag('consent', 'default', ...) for ad_storage, ad_user_data, ad_personalization and analytics_storage, restoring a previous choice from the cookieconsent_status cookie, and the banner pushes gtag('consent', 'update', ...) when the visitor chooses.

type Before a choice Allow Decline
opt-in denied granted denied
opt-out granted granted denied
info granted — —

Include the head view before the Google Tag Manager or gtag snippet, so their tags start with the consent state already set:

<head>
    @include('cookie-consent::cookie-consent-head')
    @include('gtm::head') {{-- or @include('gtag::script') --}}
</head>

Works with laravel-gtm and laravel-gtag, or any Google tag on the page. type defaults to info and consent_mode to false, so upgrading changes nothing until you opt in; run php artisan migrate after updating to add the two settings.

Privacy ledgers (LGPD, GDPR, Quebec Law 25, CCPA, US state laws)

Install one of the privacy packages below and enable its endpoint. From then on, the banner records every allow and deny there. A dismiss is not a choice, so nothing is recorded for it. You don't change any code in this package.

Package Enable What the banner records
laravel-lgpd-consent lgpd-consent.route.enabled => true consent under the purpose cookies, as proof of consent (LGPD art. 8)
laravel-gdpr-consent gdpr-consent.route.enabled => true consent under the purpose cookies, as proof of consent (GDPR Art. 7(1))
laravel-quebec-consent quebec-consent.route.enabled => true consent under the purpose cookies, for the tracking technologies that must stay off until the person agrees (Law 25, s. 8.1)
laravel-ccpa-opt-out ccpa-opt-out.route.enabled => true deny opts out of the sale or sharing of personal information (sale_sharing), allow opts back in
laravel-us-privacy-opt-out us-privacy-opt-out.route.enabled => true deny opts out of the sale of personal data (sale) and of targeted advertising (targeted_advertising), allow opts back in

If you configure lgpd-consent.purposes, gdpr-consent.purposes or quebec-consent.purposes, add cookies to that list (in categories mode: cookies_analytics, cookies_marketing and cookies_functionality, one consent per category; for the CCPA and the US state laws, refusing marketing is the opt-out). With several of them installed, each choice goes to all of them.

The request sends the XSRF-TOKEN cookie, so it keeps working on cached pages. If that cookie is missing, it falls back to the page's CSRF token. The request uses keepalive, so it completes even when the visitor leaves the page right away.

The latest choice stays pending in localStorage until the server confirms it, one slot per package. Only one request per package is in flight at a time, so the latest choice is always the last one recorded. When a request fails, it is retried twice, and if it still fails it is sent again on the next page load. A request the server rejects for good (a 4xx other than 419 or 429) is dropped.

Blocking scripts until consent

Under the LGPD and the GDPR, analytics and marketing cookies need consent before they are set. Run php artisan migrate after updating (every new setting is off), turn on block_scripts, and the scripts of these packages wait for the visitor to allow their category:

$settings = cookie_consent_settings();
$settings->type = 'opt-in';
$settings->block_scripts = true;
$settings->save();
Category Packages
analytics gtag, clarity, hotjar, mixpanel, amplitude, matomo
marketing gtm, pixel
functionality crisp, tawk-to
never blocked (no cookies) plausible, fathom, simple-analytics, pirsch, cloudflare-web-analytics, goatcounter, umami

Each package renders its <script> with type="text/plain" data-category="…", and this package runs it, with its CSP nonce, once the category is allowed: on opt-in after allow, on opt-out right away unless the visitor declines. Google tags are left to Consent Mode when consent_mode is on. Change a category with script_categories (['plausible' => 'analytics', 'pixel' => '']; "" never blocks). Your own scripts work the same way:

<script type="text/plain" data-category="marketing">/* runs once marketing is allowed */</script>

A refusal after a script ran takes effect on the next page load. The packages ask for their attributes through cookie_consent_script_attributes('<id>') behind function_exists(), so none of them requires this package.

With honor_gpc on, a Global Privacy Control signal refuses the marketing category (and the ad signals of Consent Mode), as the CCPA and several US state laws require.

A choice per category

Set mode to categories for a banner with Accept all, Reject all and Manage preferences, where the visitor turns each category on or off, as the European data protection authorities and the ANPD expect. It uses vanilla-cookieconsent 3 and shows the categories of the packages installed (analytics and marketing when none is). The texts come from cookie-consent::preferences and the content_* settings; position places the box. Consent Mode then follows each category: analytics_storage the analytics one, the ad signals the marketing one.

Any element with data-cc="show-preferencesModal" reopens the preferences.

Cookie policy

@include('cookie-consent::policy')

renders the cookie table of your cookie policy, grouped by category and translated: the session, XSRF and consent cookies, the cookies of the privacy ledgers installed, and those of the packages above that are installed. Add your own rows:

@include('cookie-consent::policy', ['cookies' => [
    ['theme', 'This website', 'Remembers the dark mode.', '1 year', 'functionality'],
]])

Lifetimes are written like 1 year or 30 minutes (or session) and shown in the app locale. In categories mode the table ends with a button that reopens the preferences.

Content Security Policy

When your app sets a CSP nonce through Laravel's Vite (Vite::useCspNonce(), as laravel-security-headers does), every <script> this package renders carries it, so a script-src 'self' 'nonce-{nonce}' policy works without 'unsafe-inline'. Scripts loaded afterwards from the vendor's own CDN still need that host in script-src (and its API in connect-src).

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

This package uses the Osano CookieConsent plugin.

License

The MIT License (MIT). Please see License File for more information.