Architektur

Guppy folgt strikt der Shopware-6-Plugin- und Theme-Architektur. Das Theme registriert sich als shopware-platform-plugin, exponiert Konfiguration via theme.json und nutzt Twig-/SCSS-Overrides für Anpassungen.

Plugin-Struktur

DmfGuppyTheme/
├── composer.json
├── README.md
├── CLAUDE.md
├── easy-coding-standard.php
├── Makefile
├── bin/
└── src/
    ├── DmfGuppyTheme.php                # Plugin-Bootstrap
    ├── Console/                          # eigene CLI-Commands
    │   ├── ThemeCreateCommand.php
    │   └── InstallPluginsCommand.php
    ├── Command/                          # weitere CLI-Commands
    │   └── GuppyUpgradeScanCommand.php
    ├── Twig/                             # eigene Twig-Extensions
    │   └── CategoryOneLevelExtension.php
    └── Resources/
        ├── config/
        │   ├── plugin.png
        │   ├── services.xml
        │   └── services/
        │       ├── commands.xml
        │       ├── console.xml
        │       ├── cms.xml
        │       └── custom-fields.xml
        ├── theme.json                    # Theme-Konfiguration
        ├── views/
        │   └── storefront/               # Twig-Overrides
        ├── snippet/
        └── app/
            └── storefront/
                ├── src/
                │   ├── main.js           # JS-Entry
                │   ├── js/               # Storefront-Plugins
                │   └── scss/             # SCSS-Architektur
                └── dist/                 # Build-Output

Vollständige SCSS-Verzeichnisstruktur

Detail-Übersicht in Variablen & Tokens.

theme.json-Modell

theme.json ist die zentrale Steuerungsinstanz. Jedes Feld kann via theme_config('feld-name') aus Twig gelesen werden.

{
  "name": "DmfGuppyTheme",
  "author": "digital.manufaktur GmbH",
  "views": ["@Storefront", "@Plugins", "@DmfGuppyTheme"],
  "style": [
    "app/storefront/src/scss/overrides.scss",
    "@StorefrontBootstrap",
    "@Plugins",
    "app/storefront/src/scss/skin/shopware/base.scss",
    "app/storefront/src/scss/base.scss"
  ],
  "script": [
    "@Storefront",
    "@Plugins",
    "app/storefront/dist/storefront/js/dmf-guppy-theme.js"
  ],
  "asset": ["@Storefront", "@Plugins", "app/storefront/dist/assets"],
  "configInheritance": ["@Storefront"],
  "config": {
    "tabs": { },
    "blocks": { },
    "fields": { }
  }
}

Tabs, Blocks und Fields

theme.json gliedert die Konfiguration hierarchisch:

• Tabs: Top-Level-Reiter im Admin (Layout, Header, Footer, Checkout, …).
• Blocks: Gruppen innerhalb eines Tabs (themeColors, typography, layoutGeneral, …).
• Fields: einzelne Konfigurationsfelder mit Typ, Default, Optionen und Lokalisierung.

Beispielfeld:

"guppy-footer": {
    "label": {
        "en-GB": "Footer variant",
        "de-DE": "Footer Variante"
    },
    "type": "text",
    "value": "guppy-default",
    "custom": {
        "componentName": "sw-single-select",
        "options": [
            { "value": "default", "label": { "de-DE": "Shopware Standard" } },
            { "value": "guppy-default", "label": { "de-DE": "Guppy Standard" } }
        ]
    },
    "editable": true,
    "tab": "footer",
    "block": "layoutFooter",
    "order": 100
}

Vererbungs-Kette

Style-Inheritance (SCSS)

Das style-Array in theme.json definiert die exakte Compile-Reihenfolge:

overrides.scss (lädt zuerst, frühe Variablen-Overrides)
   ↓
@StorefrontBootstrap (Bootstrap)
   ↓
@Plugins (Guppy- und Drittplugins)
   ↓
skin/shopware/base.scss (Shopware-Integration)
   ↓
base.scss (Theme-Styles)

Child-Theme-Vererbung

Ein Child-Theme legt zusätzliche Layer obendrauf:

overrides.scss (Child)        ← lädt zuerst, erlaubt Variablen-Overrides
   ↓
@DmfGuppyTheme                ← gesamtes Parent-Theme
   ↓
base.scss (Child)             ← Selektoren-Styles, lädt zuletzt

Config-Inheritance

configInheritance: ["@Storefront", "@DmfGuppyTheme"]

Diese Reihenfolge ist im generierten Child-Theme fest verdrahtet: Felder-Defaults stammen aus dem Parent, Werte können im Child-Admin überschrieben werden.

Twig-Override-Modell

Templates unter Resources/views/storefront/... spiegeln das Original-Layout des Storefront-Themes. Ein Override mit sw_extends verändert nur die nötigen Blocks:

{# Resources/views/storefront/layout/header/header.html.twig #}
{% sw_extends '@Storefront/storefront/layout/header/header.html.twig' %}

{% block layout_header_logo %}
    <div class="header-logo-custom">
        {{ parent() }}
    </div>
{% endblock %}

Detailliert in Twig-Overrides.

Storefront-JS-Modell

Storefront-Plugins folgen Shopwares Standard-Pattern:

• PluginBase-Klasse mit init(), destroy()-Lifecycle.
• Registrierung im PluginManager mit Selektor.
• Initialisierung über data-*-Attribute in HTML.

Detailliert in Storefront-JS.

Console-Commands

DmfGuppyTheme registriert eigene Konsolen-Befehle:

Befehl	Service	Zweck
guppy:theme:create	Console\ThemeCreateCommand	Erstellt ein Child-Theme-Skelett (custom/static-plugins/<TechnicalName>/).
guppy:install:plugins	Console\InstallPluginsCommand	Installiert empfohlene Plugins via Composer (interaktiv).
guppy:upgrade:scan	Command\GuppyUpgradeScanCommand	Analysiert installierte Guppy-Komponenten gegen eine Shopware-Version.

Konfiguration in Resources/config/services/commands.xml und services/console.xml.

Plugin-Dependencies

Plugin	Abhängigkeit
DmfGuppyTheme	dmf/sw6-plugin-splide-slider
DmfGuppyEmotionworldElements	dmf/sw6-guppy-theme: ^2.0
Slider-Custom-Elements von DmfCmsCustomElements	DmfSplideSlider

Vollständige Plugin-Liste: Plugins.

Designentscheidungen

Entscheidung	Grund
Bootstrap 5 statt eigenes CSS-System	Kompatibilität zum Shopware-Default-Storefront, geteiltes Wissen, Utilities.
theme.json als zentrale Konfiguration	Anpassbarkeit ohne Code-Eingriffe, klare Trennung zwischen Parent und Child.
Splide statt Tiny-Slider	Bessere Performance, vollständige Tastatur-Navigation, Single-Source-of-Truth-Plugin.
Skip-Links und ARIA-Defaults	Barrierefreiheit als Default, nicht als Add-on.
Staging-Branch-Workflow	Trennung zwischen QA (stage) und Production (main). Major Releases nutzen RC-Tags (2.8.0-rc1) statt eigenem Branch.

Verwandte Themen

• Lokale Einrichtung: wie du das Plugin lokal lauffähig bekommst.
• Variablen & Tokens: komplette SCSS-Architektur.
• Twig-Overrides: Override-Patterns mit sw_extends.
• Plugin-Integration: eigene Plugins ins Guppy-Theme einbinden.