Skip to content

Commit e766ef8

Browse files
skerbisskerbis
committed
5.2.0-dev
1 parent 2749a5e commit e766ef8

File tree

6 files changed

+322
-77
lines changed

6 files changed

+322
-77
lines changed

‎CHANGELOG.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@
22

33
## Version 5.2.0 - unreleased
44

5-
## Version 5.1.4 - 18.12.2025
5+
### 🚀 Features
6+
7+
* **Neue Public API**: Einführung der Klasse `FriendsOfRedaxo\ConsentManager\ConsentManager` für den einfachen Zugriff auf gecachte Daten (Cookies, Gruppen, Texte, Domains)
8+
* **Performance**: Interne Klassen (`Frontend`, `InlineConsent`, `GoogleConsentMode`) nutzen nun den Cache statt direkter SQL-Abfragen
9+
* **API Dokumentation**: Neue Dokumentation der öffentlichen API in der README.md
610

711
### 🐛 Bugfixes
812

‎README.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1348,6 +1348,130 @@ Der Inline-Consent generiert ansprechende Platzhalter:
13481348

13491349
---
13501350

1351+
1352+
# API Dokumentation
1353+
1354+
Das Consent Manager Addon stellt eine öffentliche API bereit, um auf Konfigurationsdaten, Cookies und Platzhalter zuzugreifen sowie Consent-Abfragen im Frontend zu generieren.
1355+
1356+
## Datenabruf (ConsentManager)
1357+
1358+
Die Klasse `FriendsOfRedaxo\ConsentManager\ConsentManager` dient als zentrale Schnittstelle zum Abruf von gecachten Daten. Alle Methoden sind statisch.
1359+
1360+
### Cookie Daten abrufen
1361+
1362+
Gibt die vollständigen Daten eines Cookies (Services) zurück.
1363+
1364+
```php
1365+
use FriendsOfRedaxo\ConsentManager\ConsentManager;
1366+
1367+
// Für die aktuelle Sprache
1368+
$data = ConsentManager::getCookieData('youtube');
1369+
1370+
// Für eine spezifische Sprache (z.B. ID 2)
1371+
$data = ConsentManager::getCookieData('youtube', 2);
1372+
```
1373+
1374+
**Rückgabewert:** `array|null` - Die Daten des Cookies oder `null`, wenn nicht gefunden.
1375+
1376+
### Platzhalter Daten abrufen
1377+
1378+
Gibt speziell die konfigurierten Platzhalter-Informationen (Bild und Text) für einen Service zurück. Dies ist hilfreich, um eigene Consent-Blocker zu bauen.
1379+
1380+
```php
1381+
use FriendsOfRedaxo\ConsentManager\ConsentManager;
1382+
1383+
$placeholder = ConsentManager::getPlaceholderData('youtube');
1384+
1385+
if ($placeholder) {
1386+
echo $placeholder['image']; // Dateiname im Medienpool
1387+
echo $placeholder['text']; // Platzhalter-Text
1388+
}
1389+
```
1390+
1391+
**Rückgabewert:** `array{image: string, text: string}|null`
1392+
1393+
### Alle Cookies abrufen
1394+
1395+
Gibt alle konfigurierten Cookies für eine Sprache zurück.
1396+
1397+
```php
1398+
$cookies = ConsentManager::getCookies();
1399+
// oder $cookies = ConsentManager::getCookies($clangId);
1400+
```
1401+
1402+
### Cookie-Gruppen abrufen
1403+
1404+
Gibt alle Cookie-Gruppen zurück.
1405+
1406+
```php
1407+
$groups = ConsentManager::getCookieGroups();
1408+
```
1409+
1410+
### Texte abrufen
1411+
1412+
Gibt alle im Addon konfigurierten Texte für das Frontend zurück.
1413+
1414+
```php
1415+
$texts = ConsentManager::getTexts();
1416+
echo $texts['consent_manager_accept_all']; // Beispiel
1417+
```
1418+
1419+
### Domains abrufen
1420+
1421+
Gibt alle konfigurierten Domains zurück.
1422+
1423+
```php
1424+
$domains = ConsentManager::getDomains();
1425+
```
1426+
1427+
### Domain-Konfiguration abrufen
1428+
1429+
Gibt die Konfiguration einer spezifischen Domain zurück.
1430+
1431+
```php
1432+
$domainConfig = ConsentManager::getDomain('example.org');
1433+
```
1434+
1435+
## Inline Consent (InlineConsent)
1436+
1437+
Die Klasse `FriendsOfRedaxo\ConsentManager\InlineConsent` ermöglicht die Ausgabe von blockierten Inhalten, die erst nach Zustimmung geladen werden (z.B. YouTube-Videos, Iframes).
1438+
1439+
### Inhalt mit Consent-Abfrage ausgeben
1440+
1441+
Umschließt einen Inhalt (z.B. Iframe) oder eine Video-ID mit dem Consent-Platzhalter.
1442+
1443+
```php
1444+
use FriendsOfRedaxo\ConsentManager\InlineConsent;
1445+
1446+
// Einfachste Verwendung mit Service-Key und Inhalt
1447+
$content = '<iframe src="..."></iframe>';
1448+
echo InlineConsent::doConsent('youtube', $content);
1449+
```
1450+
1451+
**Mit Optionen:**
1452+
1453+
```php
1454+
$options = [
1455+
'title' => 'Mein Video',
1456+
'width' => '100%',
1457+
'height' => '400px',
1458+
'thumbnail' => 'my_image.jpg', // oder 'auto' für automatische Thumbnails bei YouTube/Vimeo
1459+
'attributes' => ['class' => 'my-video-class']
1460+
];
1461+
1462+
// Bei YouTube/Vimeo kann auch direkt die ID oder URL übergeben werden
1463+
echo InlineConsent::doConsent('youtube', 'https://youtu.be/dQw4w9WgXcQ', $options);
1464+
```
1465+
1466+
### CSS und JavaScript manuell ausgeben
1467+
1468+
Falls benötigt, können CSS und JS für den Inline-Consent manuell ausgegeben werden. Im Normalfall werden diese Assets automatisch eingebunden, sobald `doConsent` aufgerufen wird.
1469+
1470+
```php
1471+
echo InlineConsent::getCSS();
1472+
echo InlineConsent::getJavaScript();
1473+
```
1474+
13511475
## 📄 Lizenz und Credits
13521476

13531477
### Lizenz

‎lib/ConsentManager.php‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
<?php
2+
3+
namespace FriendsOfRedaxo\ConsentManager;
4+
5+
use rex_addon;
6+
use rex_clang;
7+
8+
class ConsentManager
9+
{
10+
/** @var array<mixed> */
11+
private static $cache = [];
12+
13+
private static function initCache(): void
14+
{
15+
if (empty(self::$cache)) {
16+
self::$cache = Cache::read();
17+
// Ensure cache is populated if empty or version mismatch
18+
if (empty(self::$cache) || (rex_addon::get('consent_manager')->getVersion() !== (self::$cache['majorVersion'] ?? null))) {
19+
Cache::forceWrite();
20+
self::$cache = Cache::read();
21+
}
22+
}
23+
}
24+
25+
/**
26+
* Returns the full cache array.
27+
*
28+
* @return array<mixed>
29+
* @api
30+
*/
31+
public static function getCache(): array
32+
{
33+
self::initCache();
34+
return self::$cache;
35+
}
36+
37+
/**
38+
* Returns the cookie data for a given cookie uid.
39+
*
40+
* @param string $uid The cookie uid
41+
* @param int|null $clangId The clang id (optional, defaults to current clang)
42+
* @return array<string, mixed>|null Returns the cookie data array, or null if not found.
43+
* @api
44+
*/
45+
public static function getCookieData(string $uid, ?int $clangId = null): ?array
46+
{
47+
if (null === $clangId) {
48+
$clangId = rex_clang::getCurrentId();
49+
}
50+
51+
self::initCache();
52+
53+
return self::$cache['cookies'][$clangId][$uid] ?? null;
54+
}
55+
56+
/**
57+
* Returns all domains from cache.
58+
*
59+
* @return array<string, mixed>
60+
* @api
61+
*/
62+
public static function getDomains(): array
63+
{
64+
self::initCache();
65+
return self::$cache['domains'] ?? [];
66+
}
67+
68+
/**
69+
* Returns data for a specific domain.
70+
*
71+
* @param string $domain
72+
* @return array<string, mixed>|null
73+
* @api
74+
*/
75+
public static function getDomain(string $domain): ?array
76+
{
77+
self::initCache();
78+
return self::$cache['domains'][$domain] ?? null;
79+
}
80+
81+
/**
82+
* Returns cookie groups for a language.
83+
*
84+
* @param int|null $clangId
85+
* @return array<string, mixed>
86+
* @api
87+
*/
88+
public static function getCookieGroups(?int $clangId = null): array
89+
{
90+
self::initCache();
91+
if (null === $clangId) {
92+
$clangId = rex_clang::getCurrentId();
93+
}
94+
return self::$cache['cookiegroups'][$clangId] ?? [];
95+
}
96+
97+
/**
98+
* Returns cookies for a language.
99+
*
100+
* @param int|null $clangId
101+
* @return array<string, mixed>
102+
* @api
103+
*/
104+
public static function getCookies(?int $clangId = null): array
105+
{
106+
self::initCache();
107+
if (null === $clangId) {
108+
$clangId = rex_clang::getCurrentId();
109+
}
110+
return self::$cache['cookies'][$clangId] ?? [];
111+
}
112+
113+
/**
114+
* Returns texts for a language.
115+
*
116+
* @param int|null $clangId
117+
* @return array<string, string>
118+
* @api
119+
*/
120+
public static function getTexts(?int $clangId = null): array
121+
{
122+
self::initCache();
123+
if (null === $clangId) {
124+
$clangId = rex_clang::getCurrentId();
125+
}
126+
return self::$cache['texts'][$clangId] ?? [];
127+
}
128+
129+
/**
130+
* Returns the version from cache.
131+
*
132+
* @return string
133+
* @api
134+
*/
135+
public static function getVersion(): string
136+
{
137+
self::initCache();
138+
return self::$cache['majorVersion'] ?? '';
139+
}
140+
141+
/**
142+
* Returns the cache log ID.
143+
*
144+
* @return string
145+
* @api
146+
*/
147+
public static function getCacheLogId(): string
148+
{
149+
self::initCache();
150+
return (string) (self::$cache['cacheLogId'] ?? '');
151+
}
152+
153+
154+
/**
155+
* Returns the placeholder data for a given cookie uid.
156+
*
157+
* @param string $uid The cookie uid
158+
* @param int|null $clangId The clang id (optional, defaults to current clang)
159+
* @return array{image: string, text: string}|null Returns an array with 'image' and 'text' keys, or null if not found.
160+
* @api
161+
*/
162+
public static function getPlaceholderData(string $uid, ?int $clangId = null): ?array
163+
{
164+
$cookie = self::getCookieData($uid, $clangId);
165+
166+
if ($cookie) {
167+
return [
168+
'image' => $cookie['placeholder_image'] ?? '',
169+
'text' => $cookie['placeholder_text'] ?? '',
170+
];
171+
}
172+
173+
return null;
174+
}
175+
}

‎lib/Frontend.php‎

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -63,13 +63,9 @@ public function __construct(int $forceWrite = 0)
6363
if (1 === $forceWrite) {
6464
Cache::forceWrite();
6565
}
66-
$this->cache = Cache::read();
67-
if (0 === count($this->cache) || (rex_addon::get('consent_manager')->getVersion() !== ($this->cache['majorVersion'] ?? null))) {
68-
Cache::forceWrite();
69-
$this->cache = Cache::read();
70-
}
71-
$this->cacheLogId = $this->cache['cacheLogId'] ?? '';
72-
$this->version = $this->cache['majorVersion'] ?? '';
66+
$this->cache = ConsentManager::getCache();
67+
$this->cacheLogId = ConsentManager::getCacheLogId();
68+
$this->version = ConsentManager::getVersion();
7369
}
7470

7571
/**
@@ -113,22 +109,23 @@ public function setDomain(string $domain)
113109
// Domain immer in Kleinbuchstaben normalisieren für den Lookup
114110
$domain = Utility::hostname();
115111

116-
if (!isset($this->cache['domains'])) {
112+
$domains = ConsentManager::getDomains();
113+
if (empty($domains)) {
117114
return;
118115
}
119116

120117
// Zuerst exakte Domain suchen
121-
if (isset($this->cache['domains'][$domain])) {
118+
if (isset($domains[$domain])) {
122119
$this->domainName = $domain;
123120
} else {
124121
// Dann HTTP_HOST versuchen (für Fälle mit Port oder Subdomain)
125122
$httpHost = strtolower(rex_request::server('HTTP_HOST'));
126-
if (isset($this->cache['domains'][$httpHost])) {
123+
if (isset($domains[$httpHost])) {
127124
$this->domainName = $httpHost;
128125
} else {
129126
// Domain ohne Port versuchen
130127
$httpHostNoPort = preg_replace('/:\d+$/', '', $httpHost);
131-
if (isset($this->cache['domains'][$httpHostNoPort])) {
128+
if (isset($domains[$httpHostNoPort])) {
132129
$this->domainName = $httpHostNoPort;
133130
} else {
134131
return;
@@ -137,11 +134,11 @@ public function setDomain(string $domain)
137134
}
138135

139136
// Zusätzliche Sicherheitsabfrage
140-
if ('' === $this->domainName || !isset($this->cache['domains'][$this->domainName])) {
137+
if ('' === $this->domainName || !isset($domains[$this->domainName])) {
141138
return;
142139
}
143140

144-
$domainData = $this->cache['domains'][$this->domainName];
141+
$domainData = $domains[$this->domainName];
145142

146143
// Sicherstellen, dass Domain-Daten ein Array sind
147144
if (!is_array($domainData)) {

0 commit comments

Comments
 (0)