Gdpr Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require nucleos/gdpr-bundle
   

2. Enable the Bundle in config/bundles.php:

   Nucleos\NucleosGDPRBundle\NucleosGDPRBundle::class => ['all' => true],
   

3. Configure Basic Blocking (optional, but recommended):

   # config/packages/nucleos_gdpr.yaml
   nucleos_gdpr:
       block_cookies: null  # Blocks all cookies by default
   

4. Include Frontend Assets: Add GdprPopup.js and GdprPopup.css to your Webpack Encore setup:

   // webpack.config.js
   Encore
       .addEntry('gdpr', './assets/gdpr/GdprPopup.js')
       .enableSassLoader()
       .copyFiles({
           from: './assets/gdpr/GdprPopup.css',
           to: 'css/[name].css'
       });
   

5. Render the GDPR Block in your Twig template:

   {{ sonata_block_render({
       'type': 'nucleos_gdpr.block.information',
       'url': 'https://your-site.com/privacy-policy',
       'text': 'We use cookies to enhance your experience.'
   }) }}
   

Implementation Patterns

Cookie Management Workflow

1. Define Allowed Cookies:

   nucleos_gdpr:
       block_cookies:
           keep:
               - PHPSESSID
               - _csrf_token
               - ADMIN_.*  # Regex support for dynamic names
   

2. Dynamic Cookie Handling: Use the NucleosGDPRBundle\EventListener\CookieListener to hook into Symfony’s kernel.request event:

   // src/EventListener/CustomGDPRListener.php
   namespace App\EventListener;
   
   use Nucleos\NucleosGDPRBundle\EventListener\CookieListener;
   use Symfony\Component\HttpKernel\Event\RequestEvent;
   
   class CustomGDPRListener extends CookieListener {
       public function onKernelRequest(RequestEvent $event) {
           // Extend logic (e.g., whitelist additional cookies conditionally)
           $this->allowedCookies[] = 'CUSTOM_COOKIE_' . $event->getRequest()->get('user_id');
           parent::onKernelRequest($event);
       }
   }
   

   Register the listener in services.yaml:

   services:
       App\EventListener\CustomGDPRListener:
           tags:
               - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }
   

3. Conditional Blocking: Override the block_cookies config per environment:

   # config/packages/dev/nucleos_gdpr.yaml
   nucleos_gdpr:
       block_cookies: ~  # Allow all cookies in dev
   

Frontend Integration

1. Customize the Popup: Extend GdprPopup.js to match your theme:

   // assets/gdpr/GdprPopup.js
   const GdprPopup = {
       // Override default options
       options: {
           acceptButtonText: 'Allow All Cookies',
           rejectButtonText: 'Reject All',
           customStyles: {
               container: 'bg-white p-4 rounded shadow-lg',
               button: 'mr-2'
           }
       },
       // Add custom logic
       onAccept() {
           this.setCookieConsent(true);
           // Trigger analytics or other post-consent actions
           window.dataLayer = window.dataLayer || [];
           window.dataLayer.push({ event: 'gdpr_consent_granted' });
       }
   };
   

2. Event Handling: Listen for consent events in your frontend:

   document.addEventListener('gdprConsentGranted', (e) => {
       console.log('User granted consent:', e.detail);
       // Load non-essential scripts (e.g., analytics)
       loadAnalyticsScript();
   });
   

3. Server-Side Consent Check: Verify consent in controllers:

   // src/Controller/SomeController.php
   use Nucleos\NucleosGDPRBundle\Service\GDPRService;
   
   class SomeController {
       public function __construct(private GDPRService $gdprService) {}
   
       public function analytics(Request $request) {
           if (!$this->gdprService->isConsentGiven($request)) {
               return new Response('Consent required', 403);
           }
           // Proceed with analytics
       }
   }
   

Privacy Headers

1. Customize Permissions-Policy: Extend the default header in config/packages/nucleos_gdpr.yaml:

   nucleos_gdpr:
       privacy:
           permissions_policy: "geolocation=(), microphone=(), camera=(), payment=()"
   

   Or disable entirely:

   nucleos_gdpr:
       privacy:
           permissions_policy: null
   

2. Google FLoC: Enable/disable via config:

   nucleos_gdpr:
       privacy:
           google_floc: false  # Disable by default (recommended)
   

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • The bundle is archived and no longer maintained. Use klaro.js for new projects.
   • Migration Tip: If stuck with this bundle, fork it and maintain it internally.

2. Cookie Blocking Overhead:

   • Blocking all cookies by default (block_cookies: null) may break functionality (e.g., CSRF tokens, sessions). Always whitelist essential cookies.
   • Debugging: Check blocked cookies in browser dev tools (Application > Cookies). Look for gdpr_blocked flag.

3. Sonata Block Dependency:

   • The bundle requires sonata/block-bundle. If not using Sonata, the nucleos_gdpr.block.information block won’t work.
   • Workaround: Use a custom Twig include or controller-based GDPR notice.

4. Frontend Asset Conflicts:

   • Ensure GdprPopup.js and GdprPopup.css are loaded after jQuery (if used) to avoid $ is not defined errors.
   • Fix: Add a dependency in Encore:

     Encore
         .addEntry('gdpr', './assets/gdpr/GdprPopup.js')
         .setPublicPath('/build')
         .splitEntry('gdpr')
         .autoProvidejQuery();
     

Debugging Tips

1. Log Blocked Cookies: Enable debug mode in nucleos_gdpr.yaml:

   nucleos_gdpr:
       debug: true  # Logs blocked/allowed cookies to Symfony profiler
   

   Check the Profiler > GDPR tab for details.

2. Test Cookie Blocking:

   • Use a tool like EditThisCookie to manually set/clear cookies and verify behavior.
   • Test Case:

     // src/Tests/Functional/GDPRCookieTest.php
     use Nucleos\NucleosGDPRBundle\Service\GDPRService;
     
     class GDPRCookieTest extends WebTestCase {
         public function testCookieBlocking() {
             $client = static::createClient();
             $client->request('GET', '/');
             $cookies = $client->getCookieJar()->all();
             $this->assertArrayHasKey('gdpr_blocked', $cookies['PHPSESSID'] ?? []);
         }
     }
     

3. Consent Persistence:

   • By default, consent is stored in a cookie named gdpr_consent. If this cookie is blocked, consent won’t persist.
   • Fix: Whitelist gdpr_consent in block_cookies.keep.

Extension Points

1. Custom Consent Storage: Override the default cookie storage by implementing Nucleos\NucleosGDPRBundle\Storage\ConsentStorageInterface:

   // src/Storage/CustomConsentStorage.php
   namespace App\Storage;
   
   use Nucleos\NucleosGDPRBundle\Storage\ConsentStorageInterface;
   
   class CustomConsentStorage implements ConsentStorageInterface {
       public function saveConsent(bool $consent): void {
           // Save to database or session
           $_SESSION['gdpr_consent'] = $consent;
       }
   
       public function getConsent(): ?bool {
           return $_SESSION['gdpr_consent'] ?? null;
       }
   }
   

   Register the service in services.yaml:

   services:
       Nucleos\NucleosGDPRBundle\Storage\ConsentStorageInterface: '@App\Storage\CustomConsentStorage'
   

2. Event-Driven Extensions: Listen to GDPR events:

   // src/EventListener/Consent