WSC | Varianten Extended

Version: 1.6.0
Shopware: 6.6+ / 6.7+
Lizenz: GPL-3.0-or-later
Autor: Christian – web-seo-consulting.eu

---

Beschreibung

Dieses Plugin kombiniert sechs unabhängige Funktionen für Shopware 6:

1. Varianten im Listing (product.children) – Lädt die Varianten-Kinder eines Produkts im Kategorie-Listing nach, sodass im Twig-Template auf product.children zugegriffen werden kann (z. B. für das Trusted Shops Widget als kommaseparierte SKUs via data-sku).

2. Variantenlisting per Kategorie – Ersetzt in einer markierten Kategorie die Hauptartikel vollständig durch ihre Varianten. Aktivierung erfolgt über ein Custom Field direkt an der Kategorie. Die Varianten werden mit Cover-Bild geladen und sind sofort im Listing sichtbar.

3. Variantenposition synchronisieren – Gleicht die Positionen der product_configurator_setting-Tabelle mit den Positions-Werten aus property_group_option_translation ab und aktualisiert abweichende Einträge per Shopware DAL. Unterstützt Batch-Verarbeitung, Dry-Run-Modus und automatische Ausführung per Scheduled Task.

4. Varianten-Updater (Namen & Nummern) – Generiert Variantennamen und Artikelnummern anhand frei konfigurierbarer Twig-Templates aus Vaterartikel und Eigenschafts-Optionen neu. Unterstützt Dry-Run, „nur Name"/„nur Nummer" und einen Duplikat-Schutz für Artikelnummern. Auslösbar per CLI oder über ein eigenes Admin-Modul. Läuft synchron.

5. Varianten-Bilder (aus Eigenschaftswert-Medien) – Weist jeder Variante die Bilder ihrer Eigenschaftswerte (z. B. Farbe „blau") als Produktbilder zu, in der Reihenfolge der Eigenschaften/Werte, und setzt das erste Bild als Cover. Optional werden die Bilder des Vaterartikels angehängt. Die eigene Bildergalerie der Variante wird dabei ersetzt (idempotent). Auslösbar per CLI oder Admin-Modul, mit Dry-Run.

6. Varianten auf der Produktdetailseite (page.product.children) – Lädt auf der Detailseite die Geschwister-Varianten des aktuellen Produkts nach (ProductPageLoadedEvent), sodass im Twig-Template auf page.product.children zugegriffen werden kann – jede Variante als vollständige SalesChannel-Entity (Name, Artikelnummer, Preis, Optionen inkl. Gruppe, Cover). Gegenstück zu Funktion 1, aber für die Detailseite.

Alle Funktionen sind unabhängig voneinander über die Plugin-Konfiguration bzw. per Kategorie-Custom-Field aktivierbar.

---

Aktueller Stand (v1.6.0)

Funktion	Status
Variantenposition-Sync (manuell via Admin-UI)	✅ funktioniert
Variantenposition-Sync (CLI: wsc:sync-variant-positions)	✅ funktioniert
Variantenposition-Sync (Dry-Run-Modus)	✅ funktioniert
Automatischer Hintergrund-Sync (Scheduled Task)	✅ funktioniert
Varianten im Listing (product.children)	✅ funktioniert
Varianten auf der Produktdetailseite (page.product.children)	✅ funktioniert
Variantenlisting per Kategorie (Custom Field)	✅ funktioniert
Varianten-Updater Namen/Nummern (Admin-UI)	✅ funktioniert
Varianten-Updater Namen/Nummern (CLI: wsc:update-variant-names)	✅ funktioniert
Varianten-Updater Dry-Run-Modus	✅ funktioniert
Varianten-Bilder aus Eigenschaftswerten (Admin-UI)	✅ funktioniert
Varianten-Bilder (CLI: wsc:assign-variant-images)	✅ funktioniert
Varianten-Bilder Dry-Run-Modus	✅ funktioniert

---

Installation

1. Plugin installieren und aktivieren

bin/console plugin:refresh
bin/console plugin:install --activate WSCSWPluginVariantenExtended
bin/console cache:clear

2. Wichtiger Schritt nach der Erstinstallation

Nach der Installation erscheint der Scheduled Task unter Einstellungen → Geplante Aufgaben automatisch mit dem Status „Geplant". Dies ist ein technisch bedingtes Verhalten von Shopware.

Damit der Task korrekt auf „Inaktiv" gesetzt wird:

1. Shopware Admin öffnen
2. Erweiterungen → Meine Erweiterungen → WSC | Varianten Extended → Konfiguration
3. Den Schalter „Automatische Hintergrundsynchronisation aktivieren" auf OFF lassen
4. Auf Speichern klicken

→ Der Task wird daraufhin auf Inaktiv gesetzt und läuft nicht im Hintergrund.

Soll der automatische Sync aktiv sein, den Schalter auf ON stellen und speichern → Task wird auf Geplant gesetzt.

---

Konfiguration

Karte 1 – Varianten im Listing

Einstellung	Typ	Standard	Beschreibung
variantenExtendedActive	bool	false	product.children im Listing nachladen
variantenExtendedDebug	bool	false	Debug-Logging ins Shopware-Log

Karte 2 – Sync-Verhalten (Variantenposition)

Einstellung	Typ	Standard	Beschreibung
scheduledTaskEnabled	bool	false	Automatischen Hintergrund-Sync aktivieren
scheduledTaskInterval	int	3600	Intervall in Sekunden (3600 = 1 Std., 86400 = 1 Tag)
syncVariantPositionsDebug	bool	false	Debug-Logging ins Shopware-Log
batchSize	int	500	Datensätze pro Batch

Karte 3 – Varianten-Updater (Namen & Nummern)

Einstellung	Typ	Standard	Beschreibung
variantUpdaterActive	bool	false	Guard: ohne Aktivierung werden keine Änderungen geschrieben (Dry-Run funktioniert trotzdem)
variantUpdaterDebug	bool	false	Debug-Logging ins Shopware-Log
variantUpdaterNameTemplate	text	{{ parentProduct.name }} {{ options|map(o => o.name)|join(' ') }}	Twig-Template für den Variantennamen
variantUpdaterNumberTemplate	text	{{ parentProduct.productNumber }}-{{ options|map(o => o.name|wsc_slugify)|join('-') }}	Twig-Template für die Artikelnummer (wsc_slugify erzeugt ASCII-sichere Slugs: ä→ae, ß→ss, klein, Bindestriche)
variantUpdaterNameOnly	bool	false	Standard: nur Namen aktualisieren
variantUpdaterNumberOnly	bool	false	Standard: nur Nummern aktualisieren

Karte 4 – Varianten-Bilder (aus Eigenschaftswert-Medien)

Einstellung	Typ	Standard	Beschreibung
variantImageActive	bool	false	Guard: ohne Aktivierung werden keine Bilder geschrieben (Dry-Run funktioniert trotzdem)
variantImageDebug	bool	false	Debug-Logging ins Shopware-Log
variantImageIncludeParent	bool	false	Standard für den Admin-Schalter „Vaterartikel-Bilder anhängen"

Karte 5 – Varianten auf der Produktdetailseite

Einstellung	Typ	Standard	Beschreibung
variantenDetailActive	bool	false	Geschwister-Varianten auf der Detailseite als page.product.children nachladen
variantenDetailDebug	bool	false	Debug-Logging ins Shopware-Log

Im Twig-Template der Detailseite steht danach page.product.children zur Verfügung – jede Variante als vollständige SalesChannel-Entity (inkl. options.group und cover.media). Bei Direktaufruf des Vaterartikels wird über dessen eigene ID aufgelöst; hat ein Produkt keine Geschwister, bleibt children leer.

---

Variantenlisting per Kategorie

Mit Version 1.1.0 können einzelne Kategorien so markiert werden, dass im Listing die Varianten statt der Hauptartikel angezeigt werden.

Voraussetzung

Das Plugin legt beim ersten Start automatisch das Custom Field custom_kategorien_wsc_zusatzfelder_variantenlisting in der Feldgruppe custom_kategorien_wsc_zusatzfelder an. Das Feld erscheint in der Kategorie-Bearbeitung als Switch „Variantenlisting aktivieren".

Das Custom Field und die Feldgruppe werden beim Deinstallieren des Plugins nicht gelöscht, damit bestehende Kategorieeinstellungen erhalten bleiben.

Aktivierung pro Kategorie

1. Shopware Admin öffnen
2. Kataloge → Kategorien → gewünschte Kategorie öffnen
3. Reiter „Zusatzfelder" → Gruppe „WSC Kategorien Zusatzfelder"
4. Switch „Variantenlisting aktivieren" auf ON stellen und speichern

→ In dieser Kategorie werden ab sofort die einzelnen Varianten im Listing angezeigt, nicht die Hauptartikel. Jede Variante erscheint mit eigenem Cover-Bild.

Hinweis

Das Variantenlisting greift unabhängig vom Schalter variantenExtendedActive. Es wird ausschließlich durch das Custom Field der jeweiligen Kategorie gesteuert.

---

Manueller Sync per CLI

# Vorschau (keine Änderungen)
bin/console wsc:sync-variant-positions --dry-run

# Sync für alle Produkte
bin/console wsc:sync-variant-positions

# Sync für ein einzelnes Produkt
bin/console wsc:sync-variant-positions --product-id=<UUID>

---

Admin-Modul

Das Plugin registriert ein gemeinsames Admin-Modul auf der Einstellungen-Seite in der Gruppe Erweiterungen → „WSC | Varianten Extended" (kein Eintrag in der linken Navigation).

Die Seite enthält drei Karten:

1. Variantenposition synchronisieren
2. Varianten-Updater (Namen & Nummern)
3. Varianten-Bilder (aus Eigenschaftswert-Medien)

In allen Karten wählt man einheitlich entweder bestimmte Produkte über ein Multi-Select-Dropdown (nur Vaterartikel mit Varianten) oder „alle Produkte mit Varianten" – jeweils mit Dry-Run-Vorschau und Ergebnis-Zusammenfassung. Die Bilder-Karte hat zusätzlich einen Schalter „Vaterartikel-Bilder anhängen".

---

Varianten-Updater (Namen & Nummern)

Generiert Variantennamen und Artikelnummern anhand der konfigurierten Twig-Templates (siehe Karte 3) neu. Vor dem Schreiben prüft der Updater, ob die Ziel-Artikelnummer bereits existiert (Duplikat-Schutz).

Guard: Solange variantUpdaterActive deaktiviert ist, werden keine Änderungen gespeichert. Eine Vorschau (Dry-Run) ist davon unabhängig jederzeit möglich.

Per CLI

# Vorschau für bestimmte Vaterartikel (keine Änderungen)
bin/console wsc:update-variant-names --product-numbers=SW10001,SW10002 --dry-run

# Aktualisieren für bestimmte Vaterartikel
bin/console wsc:update-variant-names --product-numbers=SW10001,SW10002

# Alle Produkte mit Varianten (mit Rückfrage)
bin/console wsc:update-variant-names --all-products

# Nur Namen bzw. nur Nummern aktualisieren
bin/console wsc:update-variant-names --product-numbers=SW10001 --name-only
bin/console wsc:update-variant-names --product-numbers=SW10001 --number-only

Per Admin-Modul

Über das gemeinsame Admin-Modul (Einstellungen → Erweiterungen → WSC | Varianten Extended), Karte „Varianten-Updater": Produkte per Dropdown auswählen oder „alle Produkte mit Varianten", optionaler Dry-Run, Ergebnis-Zusammenfassung (geprüfte/geänderte Varianten, Namen/Nummern).

---

Varianten-Bilder (aus Eigenschaftswert-Medien)

Weist jeder Variante die Bilder ihrer Eigenschaftswerte zu (in Reihenfolge der Eigenschaften/Werte) und setzt das erste Bild als Cover. Die eigene Bildergalerie der Variante wird dabei ersetzt (idempotent – ein erneuter Lauf erzeugt keine Duplikate). Eigenschaftswerte ohne Bild werden übersprungen.

Guard: Solange variantImageActive deaktiviert ist, werden keine Bilder geschrieben (Dry-Run ist davon unabhängig möglich).

Per CLI

# Vorschau für bestimmte Vaterartikel
bin/console wsc:assign-variant-images --product-numbers=SW10001,SW10002 --dry-run

# Zuweisen für bestimmte Vaterartikel
bin/console wsc:assign-variant-images --product-numbers=SW10001,SW10002

# Alle Produkte mit Varianten (mit Rückfrage), inkl. Vaterartikel-Bilder
bin/console wsc:assign-variant-images --all-products --include-parent-images

Per Admin-Modul

Einstellungen → Erweiterungen → WSC Varianten Extended, Karte „Varianten-Bilder": Produkte wählen oder „alle", optional „Vaterartikel-Bilder anhängen", Dry-Run, Ergebnis-Zusammenfassung.

---

Roadmap / geplante Erweiterungen

Der Varianten-Updater wurde bewusst zunächst schlank und synchron übernommen. Folgende Funktionen des Vorgänger-Plugins sollen später ergänzt werden (der DB-Teil wird dabei neu konzipiert):

• Asynchrone Verarbeitung über die Message Queue (Splitter- + Worker-Handler) für sehr große Kataloge
• Fortschritts-Tracking mit eigenen DB-Tabellen (Fortschritt + Fehler-Log) und Live-Anzeige im Admin
• Dynamischer Batch-Size-Calculator (passt die Batchgröße nach Laufzeit/Speicher automatisch an)
• CLI wsc:variant:debug --product-number=<NR> – Vorschau-Tabelle pro Variante (aktueller vs. neuer Wert)
• CLI --all-products im Async-Modus sowie ein --sync-Flag zur Umschaltung sync/async

Lizenz

Copyright (C) 2026 Christian Säum – web-seo-consulting.eu

Dieses Projekt steht unter der GNU General Public License, Version 3 oder (nach deiner Wahl) einer späteren Version (GPL-3.0-or-later). Der vollständige Lizenztext steht in der Datei LICENSE.

Du darfst die Software nutzen, weitergeben und – auch kommerziell – verkaufen. Gibst du eine veränderte Fassung weiter, muss deren Quellcode ebenfalls unter der GPL-3.0-or-later verfügbar sein. Der Copyright-Hinweis und die Nennung des ursprünglichen Autors dürfen nicht entfernt werden.