Cookie Consent Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require connectholland/cookie-consent-bundle
   

   (Note: The package name in the description is alessandrolandim/cookie-consent-bundle, but the README and composer.json use connectholland/cookie-consent-bundle. Use the latter.)

2. Enable the Bundle Add to config/bundles.php (Symfony 4/5):

   return [
       // ...
       ConnectHolland\CookieConsentBundle\CHCookieConsentBundle::class => ['all' => true],
   ];
   

3. Enable Routing Add to config/routes.yaml:

   ch_cookie_consent:
       resource: "@CHCookieConsentBundle/Resources/config/routing.yaml"
   

4. Basic Configuration Add to config/packages/ch_cookie_consent.yaml:

   ch_cookie_consent:
       theme: 'light'
       categories:
           - 'analytics'
           - 'tracking'
   

5. First Use Case Render the consent banner in your base template (e.g., base.html.twig):

   {{ render_esi(path('ch_cookie_consent.show_if_cookie_consent_not_set')) }}
   

Implementation Patterns

Workflow Integration

1. Conditional Loading Use show_if_cookie_consent_not_set to avoid rendering the banner after consent is given:

   {% if not chcookieconsent_isCookieConsentSavedByUser() %}
       {{ render_esi(path('ch_cookie_consent.show_if_cookie_consent_not_set')) }}
   {% endif %}
   

2. Category-Based Logic Check consent for specific categories (e.g., analytics) before loading scripts:

   {% if chcookieconsent_isCategoryAllowedByUser('analytics') %}
       {{ include('scripts_analytics.html.twig') }}
   {% endif %}
   

3. AJAX Submission Include the JS file to enable smooth submission:

   {{ asset('bundles/chcookieconsent/js/cookie_consent.js') }}
   

   (Note: Path may vary; verify via bin/console assets:install.)

4. Locale Support Pass locale dynamically:

   {{ render_esi(path('ch_cookie_consent.show_if_cookie_consent_not_set', {
       'locale': app.request.locale
   })) }}
   

Common Use Cases

• Tracking Scripts: Load Google Analytics only if analytics is allowed.
• Third-Party Widgets: Conditionally embed widgets (e.g., Facebook Pixel) based on tracking consent.
• Simplified Mode: Set simplified: true in config for a single "Accept All"/"Reject All" option.

Gotchas and Tips

Pitfalls

1. Routing Conflicts Ensure ch_cookie_consent routes don’t clash with existing routes. Use _prefix in routing.yaml if needed:

   ch_cookie_consent:
       resource: "@CHCookieConsentBundle/Resources/config/routing.yaml"
       prefix: "/cookie-consent"
   

2. Caching Issues Use render_esi (not render) to bypass Twig cache:

   {{ render_esi(path('...')) }}  {# Correct #}
   {{ render(path('...')) }}      {# Avoid #}
   

3. CSRF Protection If csrf_protection: true, ensure your form includes the CSRF token. The bundle handles this automatically for the consent form.

4. Database Logging With use_logger: true, verify the CookieConsent entity exists in your DB schema. Run migrations if needed:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

Debugging Tips

• Check Cookies: Use browser dev tools (Application > Cookies) to verify Cookie_Consent_Key and category cookies (e.g., Cookie_Category_analytics).
• Log Events: Enable Symfony’s profiler to inspect events like cookie-consent-form-submit-successful.
• Template Overrides: Clear cache after modifying templates:

  php bin/console cache:clear
  

Extension Points

1. Custom Categories Add new categories to config/packages/ch_cookie_consent.yaml and create translations in translations/messages.{locale}.yml:

   ch_cookie_consent:
       categories:
           - 'custom_category'
   

   # translations/messages.en.yml
   CookieConsent:
       custom_category: 'Custom Category'
   

2. Event Listeners Subscribe to the cookie-consent-form-submit-successful event in JavaScript:

   document.addEventListener('cookie-consent-form-submit-successful', (e) => {
       console.log('Consent saved:', e.detail);
       // Trigger analytics or other post-consent logic
   });
   

3. Styling Overrides Extend the SCSS file (Resources/assets/css/cookie_consent.scss) and rebuild assets:

   npm run dev  # If using Webpack Encore
   php bin/console assets:install
   

4. Custom Templates Override the default template by copying cookie_consent.html.twig to:

   • Symfony 4/5: templates/bundles/CHCookieConsentBundle/cookie_consent.html.twig
   • Symfony <4: app/Resources/CHCookieConsentBundle/views/cookie_consent.html.twig