Ecommercen Docs

Appearance

Cookie Consent / GDPR ​

Flow ID: CF-30 | Module(s): cookies, eshop (front controller), Cms/Cookie domain | Complexity: Medium

Business Overview ​

The Cookie Consent system provides GDPR-compliant cookie management for the storefront. It combines a client-side consent modal (Vue 2) with a server-side cookie registry (database-backed catalog of all cookies the shop uses). The consent mechanism integrates with Google Tag Manager's Consent Mode v2 to gate analytics, advertising, and personalization tracking based on visitor choices.

What visitors experience:

  • On first visit, a cookie consent banner appears at the bottom of the page
  • Three quick actions: "Accept Essentials", "Accept All", or "More Settings"
  • The details panel (lazy-loaded) shows a categorized table of all cookies the shop uses
  • The settings modal offers per-category toggles (required, analytics, advertising, personalization, ad user data, ad personalization)
  • Partial consent saves only the categories the visitor explicitly enabled
  • Consent persists for 365 days via first-party cookies; returning visitors skip the banner

What administrators do:

  • Enable/disable the cookie details feature via global settings (COOKIES.ENABLED registry key)
  • Manage the cookie catalog: add, edit, delete cookie entries with platforms, categories, data controllers, key names, domains, descriptions, retention periods, and privacy links
  • Configure which data controllers and categories are active (multi-select filters)
  • Assign CMS pages that should display an inline cookie declaration table (PAGES_TO_SHOW)

Key business behaviors:

  • Feature-gated: entire flow is disabled when COOKIES.ENABLED is false
  • Consent state is stored client-side only (browser cookies) -- no server-side consent record per visitor
  • Google Consent Mode v2 integration pushes consent default and consent update events to the dataLayer
  • Functionality storage is always granted by default; all other categories default to denied
  • Legacy session-based cookie tracking (session_cookies) coexists for backward compatibility with older tracking helpers
  • No MUI: cookie catalog is single-language (no cookies_mui table)

API Reference ​

REST Endpoints (Modern) ​

MethodPathAuthDescription
GET/rest/cms/cookieGuestList cookie catalog entries (paginated, filterable)
GET/rest/cms/cookie/itemGuestGet single cookie entry by filter
GET/rest/cms/cookie/{id}GuestGet single cookie entry by ID
POST/rest/cms/cookieBackend (Admin)Create cookie entry
POST/rest/cms/cookie/{id}Backend (Admin)Update cookie entry
DELETE/rest/cms/cookie/{id}Backend (Admin)Delete cookie entry

Filters: id (exact), categories (partial), dataControllers (partial), dataKeyNames (partial) Sorts: id, categories

Legacy JSON API (Storefront) ​

MethodPathDescription
GET/cookiesReturns cookie catalog grouped by category (JSON)

Legacy Admin ​

MethodPathDescription
GET/cookies_adminAdmin listing + filter config form
GET/cookies_admin/addAdd cookie entry form
PUT/cookies_admin/updateUpdate cookie entry (AJAX, JSON response)
POST/cookies_admin/deleteDelete cookie entry (AJAX, JSON response)
MethodPathDescription
POST/customer/set_cookiesSaves session-level cookie consent (legacy)

Code Flow ​

  1. Page load (Adv_front_controller): Passes cookieDetailsEnabled and cookiePagesToShow to the Vue app via jsonState.config
  2. Vue mount (cookiesModalMixin.js): Checks consent_status cookie
    • No consent cookie: Calls initializeDefaultState() -- sets all consent cookies to defaults, pushes gtag('consent', 'default', ...), opens the cookie modal
    • Has consent cookie: Calls initializeStateFromCookies() -- reads each consent cookie value, pushes gtag('consent', 'default', ...) with stored values
  3. User action: One of three paths:
    • Accept Essentials: Sets consent_status=true, denies ad/analytics/personalization/ad_user_data/ad_personalization, grants functionality only
    • Accept All: Sets consent_status=true, grants all categories, persists to cookies, pushes gtag('consent', 'update', ...) with all granted
    • More Settings: Switches to CookieSettings view with per-category toggles, then "Partial Consent" or "Full Consent"
  4. Cookie persistence: Each consent category is stored as a separate first-party cookie (365-day expiry) using cookie-access.js
  5. Details table (lazy-loaded): When user clicks "Details", CookieNotice fetches GET /cookies and renders a sortable, filterable table of all registered cookies

File: ecommercen/cookies/controllers/Adv_cookies_admin.php

  1. Feature gate: Every action checks $this->registry->value('COOKIES', 'ENABLED') -- returns 404 if disabled
  2. List (index): Loads active data_controllers and categories from registry, queries cookies filtered by those values, renders the admin table with inline edit and delete buttons
  3. Add (add): Form validation requires all 8 fields (platforms, categories, data_controllers, data_key_names, domains, description, retention_period, links), inserts via model
  4. Update (update): JSON response, validates id + description + links, updates via model
  5. Delete (delete): JSON response, validates numeric ID, deletes via model
  6. Registry config: Saves active DATA_CONTROLLERS, CATEGORIES, and PAGES_TO_SHOW arrays to the registry table

CMS Page Cookie Table Integration ​

File: ecommercen/category/controllers/Adv_category.php (line ~125)

When rendering a CMS page, checks if the current category_id is in the PAGES_TO_SHOW registry array. If matched, loads the cookie catalog and renders the cookies_table component inline within the page content.

View: application/views/main/cms/page.php -- conditionally includes cookiesTable component when $cookies is non-empty and COOKIES.ENABLED is true.

File: ecommercen/eshop/controllers/Adv_customer.php (setCookies method)

Stores a session-level session_cookies array with keys SESS_COOKIE_REQUIRED (1) and SESS_COOKIE_ADVERTISING (2). This is a legacy mechanism used by the tracking helper (tracking_helper.php) to conditionally include promotion tracking data attributes.

Domain Layer ​

ComponentPath
Entitysrc/Domains/Cms/Cookie/Repository/Entity.php
Repositorysrc/Domains/Cms/Cookie/Repository/Repository.php
RepositoryConfiguratorsrc/Domains/Cms/Cookie/Repository/RepositoryConfigurator.php
WriteRepositorysrc/Domains/Cms/Cookie/Repository/WriteRepository.php
Service (read)src/Domains/Cms/Cookie/Service.php
WriteServicesrc/Domains/Cms/Cookie/WriteService.php
WriteDatasrc/Domains/Cms/Cookie/WriteData.php
Validatorsrc/Domains/Cms/Cookie/Validator.php
ListRequestsrc/Domains/Cms/Cookie/ListRequest.php
DI Registrationsrc/Domains/Cms/container.php (Cookie section)

REST Layer ​

ComponentPath
Controllersrc/Rest/Cms/Controllers/Cookie.php
Resourcesrc/Rest/Cms/Resources/Cookie/Resource.php
Collectionsrc/Rest/Cms/Resources/Cookie/Collection.php
DI Registrationsrc/Rest/Cms/container.php

Legacy Layer ​

ComponentPath
Front controllerecommercen/cookies/controllers/Adv_cookies.php
Admin controllerecommercen/cookies/controllers/Adv_cookies_admin.php
Modelecommercen/cookies/models/Adv_cookies_model.php
App overridesapplication/modules/cookies/controllers/Cookies.php, Cookies_admin.php, models/Cookies_model.php

Architecture ​

Frontend Component Tree ​

CookieModal (GenericModal wrapper)
  ├── CookieNotice (banner view)
  │     ├── Accept Essentials button
  │     ├── Accept All button
  │     ├── More Settings button → opens CookieSettings
  │     └── Details panel (lazy-loaded cookie table via SimpleTable)
  └── CookieSettings (per-category toggles)
        ├── Required (always on, disabled checkbox)
        ├── Analytics toggle
        ├── Advertising toggle
        ├── Personalization toggle
        ├── Ad User Data toggle
        ├── Ad Personalization toggle
        ├── Partial Consent button
        └── Full Consent button

Additionally, CookieSettingsButton is a standalone component that re-opens the modal from anywhere (e.g., footer link).

Vuex Store ​

Module: cookies (namespaced) -- registered in assets/vue/store/index.jsFile: assets/vue/cookies/store/cookiesModule.js

State: Six consent categories, each with { defaultValue, validForDays, value }:

  • adStorage (default: denied)
  • analyticsStorage (default: denied)
  • functionalityStorage (default: granted)
  • personalizationStorage (default: denied)
  • adUserData (default: denied)
  • adPersonalization (default: denied)

Plus cookieNoticeVisible and cookieSettingsVisible for UI state.

The cookiesModalMixin.js handles dataLayer integration:

  • On mount: pushes gtag('consent', 'default', { ... }) with either default values or previously stored cookie values
  • On consent update: pushes gtag('consent', 'update', { ... }) with the new values via updateGtagConsentFromState

Mapped consent signals: ad_storage, analytics_storage, functionality_storage, personalization_storage, ad_user_data, ad_personalization. Note: security_storage is explicitly not supported.

Theme Variants ​

  • Main theme: assets/main/vue/cookies/components/ -- full implementations
  • Design theme: assets/design/vue/cookies/components/ -- extends main theme components with no overrides (extends: CookieNotice, extends: CookieModal)
  • SCSS: assets/main/scss/_cookies.scss, assets/design/scss/_cookies.scss
  • Default library theme: application/views/default/components/library/footer/scss/_footer_cookie_notice.scss, modals/footer/scss/_cookie_settings.scss

Data Model ​

cookies Table ​

ColumnTypeDescription
idint (PK, AI)Primary key
platformsvarchar(255)Platform(s) using this cookie (e.g., "web")
categoriesvarchar(255)Consent category (e.g., "analytics", "advertising")
data_controllersvarchar(255)Organization responsible (e.g., "Google LLC")
data_key_namesvarchar(255)Cookie identifiers (e.g., "_ga, _gid")
descriptionvarchar(255)Purpose description
domainsvarchar(255)Domains where cookie is set
retention_periodvarchar(255)Duration (e.g., "2 years")
linksvarchar(255)Privacy policy URL

No MUI companion table -- cookie catalog is single-language.

Registry Keys (registry table) ​

GroupKeyDescription
COOKIESENABLEDFeature toggle (boolean)
COOKIESDATA_CONTROLLERSActive data controllers filter (serialized array)
COOKIESCATEGORIESActive categories filter (serialized array)
COOKIESPAGES_TO_SHOWCMS page IDs that display the cookie declaration table (serialized array)
Cookie NameValuesExpiryPurpose
consent_statustrue365 daysWhether consent banner has been dismissed
consent_ad_storagegranted / denied365 daysAdvertising cookie consent
consent_analytics_storagegranted / denied365 daysAnalytics cookie consent
consent_functionality_storagegranted / denied365 daysFunctionality cookie consent (default: granted)
consent_personalization_storagegranted / denied365 daysPersonalization cookie consent
consent_ad_user_datagranted / denied365 daysAd user data consent
consent_ad_personalizationgranted / denied365 daysAd personalization consent

Cookies are set with domain= (root domain, no www prefix) and path=/.

Session Data (Legacy) ​

Session KeyStructurePurpose
session_cookies{ 1: bool, 2: bool }Required (1) and Advertising (2) consent. Used by tracking_helper.php for promotion data attributes.

Configuration ​

Feature Toggle ​

Enabled via admin settings panel (ecommercen/settings/controllers/Adv_settings.php):

Registry: COOKIES.ENABLED = true/false
Admin view: application/views/admin/settings/only_advisable.php (enableCookies checkbox)

Constants ​

php
// application/config/constants.php
define('SESS_COOKIE_REQUIRED', 1);
define('SESS_COOKIE_ADVERTISING', 2);

Routes ​

php
// application/config/routes.php
$route['cookies'] = 'cookies/cookies/index';
$route['cookies_admin'] = 'cookies/cookies_admin/index';
// + language-prefixed variants
php
// application/config/rest_routes.php
$route['rest/cms/cookie']['GET'] = [Cookie::class, 'index'];
$route['rest/cms/cookie/item']['GET'] = [Cookie::class, 'item'];
$route['rest/cms/cookie/(:num)']['GET'] = [Cookie::class, 'show'];
$route['rest/cms/cookie']['POST'] = [Cookie::class, 'store'];
$route['rest/cms/cookie/(:num)']['POST'] = [Cookie::class, 'update'];
$route['rest/cms/cookie/(:num)']['DELETE'] = [Cookie::class, 'destroy'];
// + language-prefixed variants

REST Policies ​

php
// application/config/rest_policies.php
Cookie::class => [
    'defaults' => ['auth' => 'backend', 'roles' => [AUTH_ROLE_ADMIN]],
    'methods'  => [
        'index' => ['auth' => 'guest'],
        'show'  => ['auth' => 'guest'],
        'item'  => ['auth' => 'guest'],
    ],
],

Read operations are public (guest); write operations require backend auth with ADMIN role.

Admin Menu ​

php
// application/config/admin_menu.php
[
    'route' => 'cookies_admin',
    'icon' => t('admin.menu.gdpr.icon'),    // fa-shield-halved
    'label' => t('admin.menu.gdpr.label'),   // "GDPR"
    'roles' => [AUTH_ROLE_ADVISABLE, AUTH_ROLE_DEVELOPER, AUTH_ROLE_ADMIN],
    'group' => 'SETTINGS'
]

Template Component ​

json
// application/config/mainTemplate.json
"cookiesTable": {
    "view": "components/cookies/cookies_table",
    "scss": ""
}

Frontend Localization ​

The following translation key groups are used:

  • cookies.* -- banner text, button labels, table headers
  • cms.cookies.* -- CMS page inline table labels
  • eshop.admin.cookies.* -- admin panel labels
  • cookies.settings.* -- settings modal labels and descriptions

Client Extension Points ​

Controller Overrides ​

The application/modules/cookies/ directory contains empty subclasses of the upstream controllers and model:

  • Cookies extends Adv_cookies -- override for custom storefront JSON behavior
  • Cookies_admin extends Adv_cookies_admin -- override afterAdd() / afterUpdate() hooks
  • Cookies_model extends Adv_cookies_model -- override query logic

Domain Layer Override ​

In a client repo, create Custom\Domains\Cms\Cookie\ classes and register DI aliases:

php
$services->alias(
    \Advisable\Domains\Cms\Cookie\WriteService::class,
    \Custom\Domains\Cms\Cookie\WriteService::class
);

Frontend Customization ​

  • Override CookieNotice.vue or CookieSettings.vue in the design theme (assets/design/vue/cookies/components/)
  • Override SCSS variables in assets/design/scss/_cookies.scss
  • The default library theme provides alternative styling in application/views/default/components/library/

Admin Hooks ​

  • afterAdd($result) -- empty hook in Adv_cookies_admin, override for post-creation logic
  • afterUpdate($result) -- empty hook in Adv_cookies_admin, override for post-update logic

CMS Page Integration ​

Add category page IDs to the PAGES_TO_SHOW registry array to display the cookie declaration table on specific CMS pages. The table renders via the cookiesTable template component.

Business Rules ​

  1. Feature gate: All cookie admin and storefront endpoints return 404 / empty array when COOKIES.ENABLED is false
  2. Default consent: Functionality storage is always granted; all other categories default to denied
  3. Required cookies: The "Required Cookies" toggle in settings is always on and disabled -- visitors cannot opt out of essential cookies
  4. Cookie domain: Consent cookies are set on the root domain (strips www. prefix) to work across subdomains
  5. No server-side consent record: Consent is stored entirely in browser cookies. There is no per-visitor consent audit trail in the database
  6. 365-day expiry: All consent cookies expire after one year; the banner reappears when consent_status expires
  7. Lazy-load details: The cookie catalog table is only fetched when the visitor clicks the "Details" button, avoiding unnecessary API calls
  8. Cache: The legacy GET /cookies endpoint uses pscache (page-scoped cache) with the front controller's TTL
  9. Admin roles: Cookie catalog management requires ADVISABLE, DEVELOPER, or ADMIN roles (admin menu); REST write operations require ADMIN role
  10. Admin validation: Add requires all 8 fields; update requires only id, description, and links (other fields are not editable after creation via the admin UI)
  11. CSV seed data: Initial cookie entries are seeded from assets/patches/cookies/updatedCookies.csv via the InitialSeed seeder, with a default Google data controller registry entry