Download the PHP package hotte512/hug-eu-label without Composer

HugEuLabel

Shopware-6.7-Plugin (GPL-3.0). Blendet das ab dem 27.09.2026 verpflichtende EU-Gewährleistungslabel in der Storefront ein, hängt es als PDF an die Bestellbestätigungs-Mail an und zeigt die seit dem 13.12.2024 verpflichtenden GPSR-Herstellerangaben (Verordnung (EU) 2023/988, Art. 19) auf der Produktdetailseite an — beide Funktionen sind unabhängig voneinander aktivierbar.

Kurz vorab: Dieses Plugin wurde überwiegend KI-gestützt entwickelt („Agentic Coding" / „Vibe Coding" mit Claude Code) und wird ohne Gewährleistung bereitgestellt (GPL-3.0) — es ist keine Rechtsberatung, die Verantwortung für die Rechtskonformität des Shops liegt beim Betreiber. Details: KI-gestützte Entwicklung und Haftungsausschluss.

Rechtsgrundlage (Kurzfassung)

• Richtlinie (EU) 2024/825 („Empowering Consumers for the Green Transition") verpflichtet Händler, Verbraucher mit einem einheitlichen Label auf die gesetzliche Gewährleistung hinzuweisen.
• Durchführungsverordnung (EU) 2025/1960 legt Layout und Text des Labels exakt fest (Anhang I). Das Label darf nicht nachgebaut oder verändert werden — nur proportionale Skalierung ist erlaubt.
• Pflichten ab 27.09.2026:
  • Das Label muss vollständig, unmittelbar sichtbar und farbig dargestellt werden — kein Accordion, Modal, Mouseover oder verkürzte Vorschau.
  • Es muss dem Verbraucher vor Vertragsabschluss zur Kenntnis gebracht werden können (Produktseite und/oder Checkout).
  • Nach dem Kauf muss es auf einem dauerhaften Datenträger vorliegen — PDF-Anhang oder eingebettetes Bild in der Bestellbestätigung. Ein bloßer Link genügt nicht.

GPSR (Produktsicherheitsverordnung)

• Verordnung (EU) 2023/988 (GPSR) gilt seit dem 13.12.2024 unmittelbar. Art. 19 verlangt bei jedem Online-Angebot eindeutig und gut sichtbar:
  • (a) Name/Handelsname bzw. Handelsmarke des Herstellers, seine Postanschrift und eine elektronische Adresse (E-Mail oder Kontakt-URL),
  • (b) bei Herstellern außerhalb der EU zusätzlich die verantwortliche Person in der EU (Art. 16) mit denselben Angaben,
  • (c) Angaben zur Identifizierung des Produkts (macht die Produktdetailseite mit Name, Bild und Artikelnummer bereits selbst),
  • (d) ggf. Warnhinweise/Sicherheitsinformationen (siehe „Phase B").
• Die Angaben müssen direkt im Produktangebot stehen — also auf der Produktdetailseite selbst. Impressum, AGB oder externe Links genügen nicht. Checkout und E-Mails sind nicht gefordert; das Plugin rendert die GPSR-Angaben deshalb ausschließlich auf der PDP.
• Anders als beim EU-Gewährleistungslabel gibt es keine Designvorgabe — die Gestaltung ist frei, darf aber nicht wie ein amtliches EU-Siegel oder Prüfzeichen wirken. Die Banner-Darstellung des Plugins ist deshalb bewusst dezent gehalten (kein Logo, keine Icons, keine Signalfarben).

Anforderungen

• Shopware ≥ 6.7 (shopware/core: ~6.7.0)
• PHP ≥ 8.2
• bacon/bacon-qr-code ^3.0 — QR-Code-Erzeugung für das GARAN-Label. Bei der Installation per Composer kommt es automatisch mit; nur bei manueller Installation separat im Shop-Root installieren.

Installation

Per Composer (empfohlen)

Vom Shopware-Root aus; Abhängigkeiten wie bacon/bacon-qr-code werden automatisch mitinstalliert:

Update:

Manuell

Das Plugin-Verzeichnis nach custom/plugins/HugEuLabel kopieren (bzw. dort klonen), dann vom Shopware-Root aus:

(In Container-Umgebungen wie DDEV/Docker die Befehle entsprechend im Container ausführen, z. B. ddev exec bin/console ….)

assets:install kopiert die Label-Dateien nach public/bundles/hugeulabel/labels/.

Das Plugin enthält die offiziellen EU-Originale des Labels für de-DE und en-GB. Herkunft, Konvertierung und das Ergänzen weiterer Sprachen sind in ASSETS.md dokumentiert.

Konfiguration

Alle Optionen unter Einstellungen → System → Plugins → EU-Label bzw. HugEuLabel.config.*, pro Sales Channel überschreibbar.

Darstellungs-Modi und Kompakt-Darstellung

Jede Anzeigefläche hat ein Auswahlfeld Darstellung: hidden (Aus), full (volles Label) oder compact. Die Kompakt-Darstellung zeigt nur den Label-Kopf als Banner — ein reiner CSS-Zuschnitt des unveränderten EU-Original-SVGs — und öffnet das volle Label per Klick, je nach compactBehavior aufklappend (Bootstrap Collapse) oder im Modal.

Rechtshinweis: Auf Produktdetailseite und Bestellabschluss-Seite muss das Label ab dem 27.09.2026 vollständig, unmittelbar sichtbar und farbig dargestellt werden. Die Kompakt-Darstellung erfüllt das nach herrschender Lesart nicht und erfolgt dort auf eigenes Risiko. Auf den freiwilligen Flächen (Warenkorb-Seite, Offcanvas) ist sie unbedenklich.

Allgemein

Die PDF-Links sind rein additiv — die Labels selbst bleiben unverändert und im Modus full unmittelbar sichtbar. Wo sie erscheinen, steuern die pdfButtons*-Schalter der jeweiligen Karte; sie greifen nur, wenn pdfButtonsMode nicht off ist. Das Gewährleistungs-PDF ist die lokalisierte Datei aus Resources/public/labels/, das GARAN-PDF wird über die Route frontend.hug_garan.label_pdf aus dem Label-SVG erzeugt.

Hinweis zum GARAN-PDF: Das Seitenformat folgt dem Label (bei der offiziellen Vorlage 200 × 211 mm bei 190 mm Label-Breite), nicht A4 — sonst bliebe ein Drittel der Seite leer. Ein Ausdruck in Originalgröße auf A4 passt trotzdem.

Die Umwandlung läuft über dompdf/php-svg-lib. Rahmen, GARAN-Schriftzug, EU-Flagge, QR-Code und die 24 Sprachzeilen liegen als Pfade vor und bleiben originalgetreu. Die drei befüllten Textfelder (Marke, Modell-Kennung, Garantiedauer) werden in Helvetica bzw. Helvetica-Bold gesetzt — php-svg-lib kann die Vorlagenschrift „Inter" nicht laden, ohne diese Substitution fiele es auf Times zurück. Maßgeblich bleibt die Storefront-Darstellung des unveränderten SVGs.

Produktdetailseite

Breiten pro Fläche

Eine feste Mindest- oder Pixelgröße schreibt die DVO (EU) 2025/1960 nicht vor, auch nicht „im Checkout größer". Auf PDP und Bestellabschluss gilt dieselbe Anforderung: vollständig, unmittelbar sichtbar, farbig und lesbar. Die Breiten werden deshalb nicht nach unten begrenzt; wählen Sie sie so, dass der Label-Text gut lesbar bleibt.

Warenkorb & Checkout

Bei custom_selector wird das Label unsichtbar gerendert und clientseitig an den konfigurierten Selektor verschoben. Wird das Ziel nicht gefunden (oder ist der Selektor leer), bleibt das Label unsichtbar und eine Warnung erscheint in der Browser-Konsole — die Seite bricht nie.

Bestellbestätigung (E-Mail)

• pdf_attachment (empfohlen): Das Plugin hängt das Label automatisch als EU-Gewaehrleistungslabel.pdf an jede Mail vom Typ order_confirmation_mail an. Fehlt die PDF-Datei, geht die Mail trotzdem raus; der Fehler wird im Log-Channel hug_eu_label protokolliert.

• inline_image: Das Plugin verändert das Mail-Template bewusst nicht programmatisch (Template-Overrides von Mail-Templates sind fragil). Der Shop-Betreiber fügt das Bild manuell in das Mail-Template order_confirmation_mail ein (Admin → Einstellungen → E-Mail-Templates), z. B.:

  Hinweis: Viele Mail-Clients blockieren SVG — für Mails empfiehlt sich eine PNG-Variante (aus dem EU-Original konvertiert, siehe ASSETS.md). Damit die Anforderung „dauerhafter Datenträger" erfüllt ist, muss das Bild eingebettet bzw. per absoluter URL dauerhaft abrufbar sein; rechtlich sicherer ist pdf_attachment.

• disabled: kein Anhang (nur sinnvoll, wenn die Pflicht anderweitig erfüllt wird).

GPSR-Herstellerangaben

Details zur Datenpflege und Anzeige-Logik im Abschnitt GPSR-Herstellerangaben pflegen.

Garantielabel GARAN (Phase 2)

Platzhalter-Card ohne Funktion. Das GARAN-Label für gewerbliche Haltbarkeitsgarantien wird in einer späteren Plugin-Version ergänzt.

GARAN-Garantielabel (gewerbliche Haltbarkeitsgarantien)

Das GARAN-Label (DVO (EU) 2025/1960, Anhang II) kennzeichnet gewerbliche Haltbarkeitsgarantien über 2 Jahre. Das Plugin befüllt die offiziellen EU-Vorlagen pro Produkt serverseitig: Marke (Herstellername), Modell-Kennung (Quelle konfigurierbar), Garantiedauer und QR-Code zu den Garantiebedingungen. Es gibt das volle Label und die offizielle Nested-Kompaktvariante (auf der PDP aufklappbar zum vollen Label).

Datenpflege

Am Hersteller (Zusatzfelder-Set „GARAN-Garantie (Hersteller-Standard)"): hug_garan_active, hug_garan_duration_years, hug_garan_conditions_url, hug_garan_conditions_media (PDF-Fallback zur URL). Am Produkt („GARAN-Garantie (Produkt-Abweichungen)"): hug_garan_disabled sowie hug_garan_product_duration_years / …_conditions_url / …_conditions_media als Overrides — damit kann ein Produkt abweichen oder auch ohne Hersteller-Garantie eigene Garantiedaten tragen.

Aktivierungsregel: Das Label erscheint nur, wenn garanEnabled an ist, das Produkt nicht deaktiviert wurde, die wirksame Dauer > 2 Jahre beträgt und Bedingungen (URL oder PDF) gepflegt sind. Unvollständige Daten unterdrücken das Label mit Warnung im Log-Channel hug_eu_label; Garantien bis 2 Jahre brauchen kein Label und bleiben still.

Konfiguration (Card „Garantielabel GARAN", pro Sales Channel)

Mail-Anhänge

conditions_pdfs hängt die als PDF gepflegten Garantiebedingungen der bestellten Produkte an (pro Datei dedupliziert; nur wo ein Media-PDF existiert). summary_pdf erzeugt die Übersicht Garantie-Uebersicht.pdf (je Position Artikel, Hersteller, Dauer, Bedingungs-Link; via dompdf). Fehler verhindern nie den Mailversand.

GPSR-Herstellerangaben pflegen

Die GPSR-Daten werden je Hersteller gepflegt: Admin → Kataloge → Hersteller → (Hersteller öffnen) → Zusatzfelder → Karte „GPSR (Produktsicherheitsverordnung)". Das Custom Field Set hug_gpsr legt das Plugin bei plugin:install/plugin:update automatisch an; bei der Deinstallation bleiben Set und Daten erhalten, außer „Alle App-Daten löschen" wird gewählt.

Die Felder sind übersetzbar (Sprachumschalter am Hersteller); die Storefront zeigt die Übersetzung der jeweiligen Sales-Channel-Sprache.

Anzeige-Logik (bei gpsrActive):

1. Hersteller hat hug_gpsr_manufacturer_info → wird angezeigt, ggf. mit verantwortlicher Person darunter.
2. Sonst (keine Daten oder Produkt ohne Hersteller) → gpsrFallbackText, sofern gefüllt.
3. Sonst → es wird nichts angezeigt — bewusst auch ohne Log-Eintrag (ein Eintrag pro Seitenaufruf wäre Log-Spam).

Rechtsrisiko: Fall 3 bedeutet, dass ein Produkt ohne die nach Art. 19 GPSR verpflichtenden Angaben angeboten wird (abmahnfähig). Entweder alle Hersteller mit GPSR-Daten versorgen oder einen globalen Fallback-Text hinterlegen — und neu angelegte Hersteller in die Pflege-Routine aufnehmen.

Positionierung: Standard ist combined — die GPSR-Angaben erscheinen am EU-Gewährleistungslabel (untereinander oder nebeneinander), und zwar auch an dessen Sonderpositionen (page_end, custom_selector, near_shipping_info). Ist das EU-Label ausgeblendet (pdpMode: hidden), erscheinen die GPSR-Angaben allein an der als pdpPosition konfigurierten Stelle. Alternativ bekommt der Block über gpsrPosition eine eigene Position. Die GPSR-Angaben erscheinen nur auf der Produktdetailseite (nicht im Checkout, nicht in E-Mails) — das entspricht der Anforderung „im Produktangebot".

Darstellung: Die Banner-Farben laufen über CSS Custom Properties (--hug-gpsr-bg, --hug-gpsr-bar, --hug-gpsr-border, --hug-gpsr-color) und lassen sich im Theme überschreiben. Alle Varianten sind auf WCAG-AA-Kontrast ausgelegt (dunkler Fließtext auf sehr hellen Flächen).

Phase B (geplant): Warnhinweise je Produkt

Produktbezogene Warnhinweise und Sicherheitsinformationen (Art. 19 lit. d GPSR) folgen bei Bedarf in einer späteren Version — vorgesehen als Zusatzfelder am Produkt. Relevant, sobald das Sortiment Produkte mit Pflicht-Warnhinweisen enthält.

Mehrsprachigkeit der Label-Dateien

Das Plugin wählt die Label-Datei anhand des Locale-Codes der Sales-Channel-Sprache: src/Resources/public/labels/{locale}/. Existiert für eine Sprache kein Ordner bzw. keine Datei, wird auf de-DE zurückgefallen. Weitere Sprachen werden ohne Code-Änderung ergänzt, indem ein neuer Locale-Ordner (z. B. en-GB/) mit gewaehrleistungslabel.svg und gewaehrleistungslabel.pdf abgelegt wird — danach assets:install ausführen.

Manueller Testplan

1. PDP: Produktdetailseite aufrufen → Label wird vollständig, farbig und ohne Interaktion sichtbar an der konfigurierten Position angezeigt (Standard: unter dem Kaufen-Button). Position in der Plugin-Config umstellen und erneut prüfen.
2. Checkout: Artikel in den Warenkorb legen, bis zur Bestellabschluss- Seite gehen → Label erscheint an der konfigurierten Position (Standard: über den AGB). Optional showOnCartPage/showOnOffcanvasCart aktivieren und Warenkorb-Seite bzw. Offcanvas prüfen.
3. Testbestellung: Bestellung abschließen → Bestellbestätigungs-Mail prüfen: Anhang EU-Gewaehrleistungslabel.pdf vorhanden und öffnet das Label. (In Dev-Umgebungen z. B. über einen Mail-Catcher wie Mailpit prüfbar.)
4. Fehlerfall: PDF temporär umbenennen, Testbestellung → Mail kommt ohne Anhang an, Warnung im Log (Log-Channel hug_eu_label).
5. Kompakt-Darstellung: pdpMode auf compact stellen → nur der blaue Label-Kopf erscheint als Banner plus Link „Gewährleistungslabel anzeigen". Klick klappt das volle Label auf (compactBehavior: collapse) bzw. öffnet es im Modal (compactBehavior: modal).
6. Benutzerdefinierte Position: pdpPosition auf custom_selector stellen, gültigen Selektor eintragen → Label erscheint am Ziel-Element. Danach absichtlich falschen Selektor eintragen → Label erscheint nicht, Browser-Konsole zeigt eine [HugEuLabel]-Warnung, die Seite funktioniert normal weiter.
7. GPSR — Daten & Fallback: gpsrActive einschalten. PDP eines Produkts, dessen Hersteller GPSR-Daten hat → Block mit Überschrift und Herstellerangaben erscheint (Zeilenumbrüche erhalten). Hersteller zusätzlich mit EU-verantwortlicher Person → zweiter Absatz mit Zwischenüberschrift „Verantwortliche Person in der EU". PDP eines Produkts, dessen Hersteller keine Daten hat → Fallback-Text erscheint; Fallback leeren → es erscheint nichts (und nichts im Log).
8. GPSR — Darstellung: gpsrDisplayMode: plain → schlichter Textblock ohne Box. banner → dezente Box; alle 5 Farbvarianten (neutral_grey, soft_blue, soft_green, outline, accent) durchschalten und prüfen, dass Text lesbar bleibt und die Box nicht wie ein Warnhinweis oder Siegel wirkt (accent übernimmt die Theme-Primärfarbe als Balken).
9. GPSR — Position combined: gpsrPosition: combined + slotLayout: stacked → GPSR-Block direkt unter dem EU-Label. side_by_side → Desktop: EU-Label links, GPSR rechts; Browserfenster unter 768 px verkleinern (oder Mobilgerät) → Blöcke stehen untereinander. pdpMode: hidden → GPSR-Block erscheint allein an der EU-Label-Position (kein leerer Rahmen daneben). Eigene Position (z. B. below_description) → Block erscheint dort unabhängig vom EU-Label.

10. GPSR — Nur PDP: Warenkorb, Checkout und Bestellbestätigungs-Mail prüfen → dort erscheinen keine GPSR-Angaben.

11. GARAN-Label: Beim Hersteller eines Testprodukts hug_garan_active, Dauer > 2 Jahre und eine Bedingungs-URL pflegen, garanEnabled aktivieren → volles Label auf der PDP (Marke, Modell-Kennung, Dauer, scanbarer QR-Code); garanPdpMode: nested → Kompakt-Banner, Klick klappt das volle Label auf/zu. garanListingMode: nested → Kompakt-Label in den Produktkacheln. Bestellabschluss zeigt das Kompakt-Label an der Position.
12. GARAN-Mail: garanMailMode: both, Testbestellung → Mail enthält Garantie-Uebersicht.pdf (und Garantiebedingungen-<Hersteller>.pdf, wenn ein PDF gepflegt ist). Unvollständige Garantiedaten (z. B. Dauer ohne Bedingungen) unterdrücken das Label mit Warnung im Log-Channel hug_eu_label.

Theme-Hinweis: Die Position „Bei den Versandinformationen" greift an Shopwares Standard-Versandinfo-Komponente. Stark angepasste Themes (etwa solche, die den Buy-Widget-Bereich per JavaScript rendern) zeigen diese Komponente nicht — dort stattdessen custom_selector verwenden. Das Ziel eines Custom-Selektors muss im initialen HTML vorhanden sein; per JavaScript nachgeladene Bereiche werden nicht gefunden.

Entwicklung

PHP- und JS-Checks: PHPStan, ECS, Rector, PHPUnit, ESLint, Jest. Konfiguration: phpstan.neon, ecs.php, rector.php, phpunit.xml.dist, .eslintrc.json, jest.config.js (Composer-Scripts: composer ecs, composer phpstan, composer phpunit, composer rector).

Unit-Tests: tests/Unit/ (LabelProvider, MailAttachmentSubscriber, GpsrProvider, GpsrCustomFieldSetInstaller, GpsrInfoTemplate/Escaping).

Entstehung: KI-gestützte Entwicklung (Agentic Coding)

Dieses Plugin wurde überwiegend KI-gestützt entwickelt („Agentic Coding" bzw. „Vibe Coding" mit Claude Code): Ein KI-Agent hat Konzeption, Implementierung, Tests und Dokumentation unter menschlicher Anleitung und Review erstellt. Der Code wurde funktional getestet (Unit-Tests, manuelle Storefront-Tests), aber nicht Zeile für Zeile von Hand geschrieben.

Was das für dich bedeutet:

• Prüfe den Code vor dem Produktiveinsatz selbst — wie bei jedem Fremd-Plugin, hier aber ausdrücklich empfohlen.
• Trotz sorgfältiger Tests können Fehler enthalten sein, die ein menschlicher Autor so nicht gemacht hätte (und umgekehrt).
• Issues und Pull Requests sind willkommen, es besteht aber kein Anspruch auf Support, Fehlerbehebung oder Weiterentwicklung.

Haftungsausschluss

• Keine Rechtsberatung: Dieses Plugin unterstützt bei der Umsetzung der Richtlinie (EU) 2024/825, der DVO (EU) 2025/1960 und der GPSR (Verordnung (EU) 2023/988). Die Zusammenfassungen der Rechtslage in dieser README sind sorgfältig recherchiert, aber keine Rechtsberatung und können falsch, unvollständig oder veraltet sein. Die Verantwortung für die Rechtskonformität des eigenen Shops (Konfiguration, Datenpflege, Fristen) liegt allein beim Shop-Betreiber; im Zweifel juristisch beraten lassen.
• Keine Gewährleistung: Die Software wird „wie besehen" bereitgestellt, ohne Gewährleistung jeglicher Art und mit Haftungsbeschränkung gemäß GPL-3.0 §§ 15–16 (siehe LICENSE). Einsatz auf eigenes Risiko — insbesondere gibt es keine Garantie, dass die Darstellung der Labels und Pflichtangaben den gesetzlichen Anforderungen im konkreten Shop genügt.

Lizenz

GNU General Public License v3.0 oder später (GPL-3.0-or-later) — Volltext in LICENSE. Copyright (C) 2026 Hotte512.

Die enthaltenen EU-Label-Dateien (Gewährleistungslabel, GARAN-Vorlagen) stammen unverändert von der Europäischen Kommission und unterliegen deren Vorgaben (insbesondere: keine inhaltliche Veränderung zulässig) — Herkunft und Details in ASSETS.md.