Cookie Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require c2is/cookie-bundle ~1.0@dev
   

   Ensure FOSJsRoutingBundle is also installed (required for JS routing).

2. Register Bundles Add to app/AppKernel.php:

   new FOS\JsRoutingBundle\FOSJsRoutingBundle(),
   new C2is\Bundle\CookieBundle\C2isCookieBundle(),
   

3. Routing Setup Add to app/config/routing.yml:

   c2is_cookie:
       resource: "@C2isCookieBundle/Resources/config/routing.yml"
   fos_js_routing:
       resource: "@FOSJsRoutingBundle/Resources/config/routing/routing.xml"
   

4. Display the Cookie Banner Embed the banner in your layout using an ESI include (recommended for caching):

   {% esi '@C2isCookieBundle:Default:cookieBanner' %}
   

   Or directly include the Twig template:

   {% render url('c2is_cookie_default_cookie_banner') %}
   

Implementation Patterns

Workflow Integration

1. Default Behavior

   • The banner appears on first visit and persists until:
     • User clicks "Accept" (sets cookie to accepted=true).
     • User dismisses it 3 times (sets cookie to dismissed=3).
   • Configure thresholds in config.yml (see Gotchas).

2. Custom Templates Override the default Twig template by creating a new template at:

   app/Resources/C2isCookieBundle/views/Default/cookieBanner.html.twig
   

   Extend the base template or replace entirely.

3. JavaScript Logic The bundle relies on fos_js_routing for AJAX calls to:

   • /cookie/accept (accept cookies).
   • /cookie/dismiss (dismiss banner). Override JS behavior by extending the cookieBundle.js asset (see Extension Points).

4. Conditional Display Hide the banner for specific routes/users by checking cookies in Twig:

   {% if not app.session.has('cookie_accepted') and not app.session.has('cookie_dismissed') %}
       {% esi '@C2isCookieBundle:Default:cookieBanner' %}
   {% endif %}
   

5. Symfony Forms Integration If using Symfony Forms, validate cookie acceptance before submission:

   use C2is\Bundle\CookieBundle\Validator\Constraints\CookieAcceptance;
   
   $builder->add('submit', SubmitType::class, [
       'constraints' => [new CookieAcceptance()],
   ]);
   

Gotchas and Tips

Pitfalls and Debugging

1. Routing Conflicts

   • Ensure fos_js_routing is loaded before C2isCookieBundle in AppKernel.
   • Verify routes are properly prefixed in routing.yml to avoid clashes.

2. Cookie Persistence

   • Cookies are stored with a 1-year expiry by default. Adjust in config.yml:

     c2is_cookie:
         cookie_lifetime: 31536000  # 1 year in seconds
         max_dismissals: 3           # Default: 3 dismissals before hiding
     

   • Debugging: Check browser cookies or Symfony’s Response headers for Set-Cookie.

3. Caching Issues

   • ESI caching may cause delays in banner updates. Use cache:clear after template changes.
   • For development, disable ESI caching temporarily:

     {% esi '@C2isCookieBundle:Default:cookieBanner' with {'cache_time': 0} %}
     

4. JavaScript Errors

   • If AJAX calls fail, verify:
     • fos_js_routing.js is loaded (check browser console).
     • Routes are accessible via /_fos_js_routing/js.
   • Override JS by extending the bundle’s asset:

     // app/Resources/public/js/cookieBundle.js
     require(['jquery'], function($) {
         $(document).ready(function() {
             // Custom logic here
         });
     });
     

     Then update the template to load your version:

     {{ parent() }}  {# Extends default template #}
     {{ js_path('bundles/c2iscookie/js/cookieBundle.js') }}
     

5. Twig Template Overrides

   • If custom templates aren’t loading, ensure:
     • The file path matches the bundle’s structure (e.g., Default/cookieBanner.html.twig).
     • The template extends the base template correctly:

       {% extends '@C2isCookieBundle/Default/cookieBanner.html.twig' %}
       

Extension Points

1. Custom Cookie Names Override cookie names in config:

   c2is_cookie:
       cookie_name: 'my_custom_cookie'
       accepted_cookie: 'accepted_flag'
       dismissed_cookie: 'dismissed_count'
   

2. Event Listeners Hook into cookie actions via Symfony events:

   // src/C2isCookieBundle/EventListener/CookieListener.php
   class CookieListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               'c2is_cookie.accept' => 'onCookieAccept',
               'c2is_cookie.dismiss' => 'onCookieDismiss',
           ];
       }
   
       public function onCookieAccept(CookieEvent $event) { /* ... */ }
   }
   

   Dispatch events in the bundle’s controller (requires extending the bundle).

3. Multi-Language Support Localize the banner by overriding the Twig template and using Symfony’s translation system:

   {{ 'cookie.banner.message'|trans }}
   

   Define translations in app/Resources/translations/messages.en.yml.