Cookie Bundle Laravel Package

Getting Started

The Cookie Bundle is a Symfony bundle from the Kunstmaan CMS family. It gives you three things: a cookie bar, a "more info" modal listing your cookie types, and a CMS page that documents them. It does not block or manage cookies — it is a UI plus a registry of consent choices that you query from your templates.

Version note: 1.7.0 is explicitly the last 1.x release. A 6.0 line is in progress (version aligned with Kunstmaan CMS 6) and the only change in 1.7.0 is the added UPGRADE-6.0.md guidance. Decide up front whether you are pinning ^1.7 for a legacy Kunstmaan CMS 5 site or waiting for / tracking the 6.0 branch for a Symfony 6 + PHP 8.2 project — the answer changes the rest of this document.

Minimal install:

composer require kunstmaan/cookie-bundle:^1.7

// config/bundles.php
Kunstmaan\CookieBundle\KunstmaanCookieBundle::class => ['all' => true],

# config/routes/kunstmaan_cookie.yaml
kunstmaan_cookie:
    resource: '@KunstmaanCookieBundle/Resources/config/routing.yml'
    prefix: /

Then install assets (bin/console assets:install, or wire the bundle's JS into Encore/Webpack) and, because the bundle ships Doctrine entities for cookie types, run bin/console doctrine:schema:update --force (or generate a migration). Confirm the dependency chain in composer.json first — the bundle is built against Kunstmaan's Node/Page/Admin bundles, so if you are not already on Kunstmaan CMS you will pull in a large stack.

Where to look first, in order:

1. README.md — copy its exact Twig include/render snippet for the bar into your base layout; the controller and template names have changed between versions.
2. UPGRADE-6.0.md — read this before writing any template overrides. It tells you what renames/removals are coming, which is exactly the list of things you should avoid depending on today.
3. Resources/config/services.yml and Helper/CookieHelper.php — this is the object your templates will call.
4. Resources/views/ — CookieBar, CookiePopup (modal), and the cookie page template you will override.
5. Resources/public/js/ — the script that writes the consent cookie and reloads the page.

First use case: put the bar in templates/layout/base.html.twig, define two or three cookie types (strictly necessary / analytics / marketing), then gate your Google Analytics snippet behind the helper and verify that declining actually stops the request.

Implementation Patterns

Treat the cookie-type list as the single source of truth. Whether the types live in bundle config or as CMS entities (check Entity/ in the version you install), the bar, the modal, and the cookie page all render from that list. Add a type once, and reference the same key everywhere — don't hardcode "analytics" strings in three places.

Gate every third-party script with the helper. This is the only real integration point:

{# templates/layout/base.html.twig #}
{% if cookie_helper.isCookieTypeAllowed('analytics') %}
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXX"></script>
    <script>window.dataLayer = window.dataLayer || []; ...</script>
{% endif %}

Do the same server-side when PHP sets non-essential cookies (personalisation, A/B assignment) — inject the helper into the service and check before calling setcookie().

Editor workflow. For Kunstmaan CMS sites, the intended pattern is to add the cookie-bar page part to the shared page template so editors can tune copy per site/locale, and publish the cookie page as a node linked from the bar's "read more". Keep the page in the footer of every layout, not just the homepage.

Override, don't fork — but keep the override layer thin. Symfony bundle template overriding works normally: templates/bundles/KunstmaanCookieBundle/CookieBar/cookiebar.html.twig. Restyle the bar and modal there, keep the underlying form action and field names intact so the bundle's save handler keeps working. Because 6.0 is coming, keep your customisations concentrated in that override directory plus one Twig helper wrapper; that makes the eventual upgrade a diff of a handful of files instead of an audit of the whole theme.

Provide a "change preferences" entry point. The bar disappears after a choice; make sure the modal can be re-opened from a footer link (call the bundle's JS function directly rather than relying on the bar button) so withdrawal of consent is as easy as giving it.

Make consent visible to the server. The bundle writes a cookie listing accepted types. Read it early (a request listener or a Twig global) so templates don't have to know the serialisation format, and so you can vary responses when caching.

Testing checklist: fresh browser → no analytics request before click; accept all → request fires; decline all → no request; save granular → only selected types fire; reload → bar stays hidden; clear cookie → bar returns; JS disabled → site still usable and nothing non-essential loads.

Gotchas and Tips

• It is not a consent management platform. No consent log, no TCF/IAB string, no script blocking, no expiry policy, no audit trail. For a real GDPR posture you either bolt those on yourself (log choices to a table, version your banner copy) or replace the bundle with Klaro/Cookiebot/Axeptio.
• Caching will bite you. If you render consent-dependent markup server-side behind a full-page cache, a page cached for an accepting visitor will leak the analytics tag to everyone. Either keep the gating client-side (read the cookie in JS and inject scripts), or add the consent cookie to your cache vary list.
• 1.7.0 is a terminal release, not a maintenance release. The changelog contains only "added upgrade info". Treat ^1.7 as a frozen dependency: no bug fixes, no security patches, no Symfony/PHP compatibility work. Pin it in composer.json, and if you need a change, vendor-fork or use an override bundle rather than expecting upstream.
• Plan for a 6.0 migration before you build. The existence of UPGRADE-6.0.md means breaking changes are already documented. Read it now, and if your project is on Symfony 6 / PHP 8.2+, prototype against the 6.0 branch first — otherwise 1.7 will fight you with return types, Twig\ namespaces, annotated routing, and --ignore-platform-req in your lock file.
• Cookie flags may not be configurable. The consent cookie is set by the bundle's JS; verify path (/), domain (subdomain sharing), Secure, and SameSite in devtools. A consent cookie scoped to www. will re-prompt on app.. This is also the sort of thing a 6.0 may change — re-check it after upgrading.
• Rejection semantics. Declining does not un-set cookies already placed on the previous response. Audit server-side cookies: session and CSRF are "strictly necessary", everything else must be conditional.
• The reload-after-save pattern causes a flash and breaks SPA-style navigation. If that matters, hook the save event and initialise your tags in place instead of reloading.
• Debugging: inspect document.cookie and the Set-Cookie response header, dump() the helper in a controller, and check that the bundle's translations exist for every locale you ship (missing keys render as raw IDs in the modal).
• Accessibility: the modal is a plain Bootstrap-style dialog; verify focus trapping, aria-modal, Escape-to-close, and keyboard reachability of the granular checkboxes before shipping — banners are a common WCAG audit finding.
• Extension points worth knowing: override the three Twig templates, decorate CookieHelper (or alias it) to add your own type logic, add cookie types via the bundle's config/entities, and extend the public JS via a small wrapper rather than editing bundle assets.