WSC Mengen-Zuschlag Plugin für Shopware 6

Automatische Zuschlagsberechnung im Warenkorb basierend auf Produktmengen und Tags.

Beschreibung

Dieses Plugin fügt automatisch Zuschläge zum Warenkorb hinzu, wenn Produkte mit bestimmten Tags eine definierte Menge erreichen. Zuschlagstypen werden komfortabel über ein eigenes Admin-Modul verwaltet (kein Eingriff in den Code nötig). Jeder Zuschlagstyp hat einen eigenen, konfigurierbaren Steuersatz und eine sprachabhängige Kundenbeschreibung.

Anwendungsbeispiel: Rollenversand für Stoffe

Ein Online-Shop verkauft Stoffe als Meterware (1 Stück = 1 Laufmeter):

• Menge 1: Stoff wird quer gerollt (max. 1m) → normales Paket
• Menge ≥2: Stoff muss längs gerollt werden (>1,4m) → Rollenversand mit Aufpreis

Über die Schwellwerte lässt sich pro Produkt steuern, ab welcher Menge ein kleiner bzw. großer Zuschlag berechnet wird.

Features

• Zuschlagstypen komfortabel im Admin verwalten (Liste + Detailformular)
• Tag-basierte Produktidentifikation
• Flexible Schwellwerte pro Produkt (kleine/große Menge) über Custom Fields
• Eigener Steuersatz pro Zuschlagstyp
• Sprachabhängiger Anzeigename und Kundenbeschreibung
• Modus „Nur 1x pro Warenkorb" (einmaliger kleiner Zuschlag)
• Automatische Hinzufügung/Aktualisierung/Entfernung bei Warenkorb-Änderungen
• Mehrsprachige Administration (DE/EN/FR)

Systemanforderungen

• Shopware 6.6.x oder 6.7.x
• PHP 8.2 oder höher (entwickelt mit PHP 8.4)

Installation

Via Composer

composer require wsc/wsc-swplugin-mengenzuschlag
bin/console plugin:refresh
bin/console plugin:install --activate WSC_SWPlugin_MengenZuschlag
bin/console cache:clear

Manuelle Installation

1. Plugin-Dateien nach custom/plugins/wsc_swplugin_mengenzuschlag/ hochladen
2. Im Admin: Erweiterungen → Meine Erweiterungen
3. Plugin installieren und aktivieren
4. Cache leeren

Bei der Installation legt das Plugin die Tabellen wsc_surcharge_type und wsc_surcharge_type_translation (lifecycle-basiert, keine Migrationen) sowie das Custom-Field-Set mit den Schwellwert-Feldern an.

Konfiguration

1. Zuschlagstypen anlegen

Navigiere zu: Einstellungen → Erweiterungen → WSC Zuschlagstypen → Neuen Typ anlegen

Pro Zuschlagstyp konfigurierbar:

Feld	Bedeutung
Name (Anzeigename)	Interner/öffentlicher Name, sprachabhängig
Tag-Name	Shopware-Tag, das am Produkt gesetzt sein muss (z. B. rollenzuschlag)
Aktiv	Typ aktivieren/deaktivieren
Nur 1x pro Warenkorb	Nur ein einzelner kleiner Zuschlag, sobald ein passender Artikel den kleinen Schwellwert erreicht
Kleine Menge Betrag (€)	Betrag für den kleinen Bereich
Große Menge Betrag (€)	Betrag für den großen Bereich
Steuersatz	Steuersatz, mit dem der Zuschlag berechnet wird (Pflichtfeld)
Interne Notiz	Nur im Admin sichtbar
Kundenbeschreibung	Wird als Label im Warenkorb angezeigt, sprachabhängig

Über den Sprachumschalter im Detailformular lassen sich Name und Kundenbeschreibung je Sprache pflegen.

2. Produkt-Konfiguration

Für jedes Produkt, das einen Zuschlag auslösen soll:

1. Tag hinzufügen (z. B. rollenzuschlag) – muss exakt dem Tag-Namen des Zuschlagstyps entsprechen.
2. Schwellwerte setzen (Custom-Field-Set „Mengen-Zuschlag Einstellungen"):
   • Artikel pro große Menge (wsc_items_per_large_quantity) – ab dieser Menge ein großer Zuschlag (0 = kein großer Zuschlag)
   • Artikel pro kleine Menge (wsc_items_per_small_quantity) – Schwellwert für den kleinen Zuschlag (0 = kein kleiner Zuschlag)
3. Speichern.

Funktionsweise

Logik

FÜR JEDEN aktiven Zuschlagstyp:
    1. Suche alle Artikel im Warenkorb, die:
       - den passenden Tag haben (z. B. "rollenzuschlag")
       - UND ein Custom Field "wsc_items_per_large_quantity" > 0 haben

    2. Berechne pro passendem Artikel:
       - gross = floor(Menge / wsc_items_per_large_quantity)
       - Rest  = Menge % wsc_items_per_large_quantity
       - klein = 1, wenn Rest > 0 UND Rest <= wsc_items_per_small_quantity
       - sonst (Rest > wsc_items_per_small_quantity) wird +1 gross berechnet

    3. Summiere gross/klein über alle passenden Artikel und füge die
       entsprechenden Zuschlag-Positionen hinzu bzw. aktualisiere sie
       (mit dem am Typ konfigurierten Steuersatz).

    4. Wenn die Bedingungen nicht mehr erfüllt sind, wird der Zuschlag
       automatisch entfernt.

Im Modus „Nur 1x pro Warenkorb" wird stattdessen genau ein kleiner Zuschlag gesetzt, sobald mindestens ein passender Artikel den kleinen Schwellwert erreicht.

Mengenmatrix (Beispiel 1)

Beispielwerte: wsc_items_per_small_quantity = 3, wsc_items_per_large_quantity = 6

Menge	Gross	Klein	Ergebnis
1	0	1	1x klein
2	0	1	1x klein
3	0	1	1x klein
4	1	0	1x gross
5	1	0	1x gross
6	1	0	1x gross
7	1	1	1x gross + 1x klein
8	1	1	1x gross + 1x klein
9	2	0	2x gross

Mengenmatrix (Beispiel 2)

Beispielwerte: wsc_items_per_small_quantity = 2, wsc_items_per_large_quantity = 5

Menge	Gross	Klein	Ergebnis
1	0	1	1x klein
2	0	1	1x klein
3	1	0	1x gross
4	1	0	1x gross
5	1	0	1x gross
6	1	1	1x gross + 1x klein
7	2	0	2x gross

Kurzformel

Pro Artikel mit passendem Tag und wsc_items_per_large_quantity > 0:

gross = floor(menge / wsc_items_per_large_quantity)
rest  = menge % wsc_items_per_large_quantity
klein = (rest > 0 UND rest <= wsc_items_per_small_quantity) ? 1 : 0
wenn (rest > wsc_items_per_small_quantity) dann gross = gross + 1

Anschließend werden gross und klein über alle passenden Artikel summiert.

Plugin-Einstellungen

Unter Erweiterungen → Meine Erweiterungen → WSC | Mengen Zuschlag → Konfigurieren:

• Debug-Modus: Aktiviert detailliertes Logging im System-Log für jede Zuschlagsberechnung. Im Live-Betrieb deaktivieren.

Entwicklung

Code-Struktur

wsc_swplugin_mengenzuschlag/
├── src/
│   ├── WSC_SWPlugin_MengenZuschlag.php          (Haupt-Plugin-Klasse, Lifecycle/Tabellen)
│   ├── Core/
│   │   ├── Checkout/Cart/
│   │   │   ├── SurchargeCartProcessor.php        (Cart-Processor: collect/process)
│   │   │   └── SurchargeLineItemFactory.php      (Factory für Zuschlag-Line-Items)
│   │   └── Content/SurchargeType/
│   │       ├── SurchargeTypeDefinition.php       (DAL-Entity Zuschlagstyp)
│   │       ├── SurchargeTypeEntity.php
│   │       ├── SurchargeTypeCollection.php
│   │       ├── SurchargeTypeTranslationDefinition.php
│   │       └── SurchargeTypeTranslationEntity.php
│   ├── Service/
│   │   ├── CustomFieldsInstaller.php             (Custom-Field-Set Installation)
│   │   └── SurchargeService.php                  (Zuschlagsberechnung)
│   └── Resources/
│       ├── app/administration/                  (Admin-Modul wsc-surcharge-types, DE/EN/FR)
│       └── config/
│           ├── config.xml                        (Plugin-Einstellung: Debug-Modus)
│           └── services.xml                      (Service-Definitionen)
├── composer.json
├── phpstan.neon
├── .php-cs-fixer.dist.php
└── README.md

Qualitätssicherung

• Code-Style: PSR-12 via php-cs-fixer (.php-cs-fixer.dist.php)
• Statische Analyse: PHPStan Level 3 (phpstan.neon)
• Beides läuft in der Forgejo-CI (.forgejo/workflows/ci.yml, ohne externe Actions); bei v*-Tags wird zusätzlich ein Installations-ZIP gebaut und als Release angehängt.

Troubleshooting

Zuschlag wird nicht hinzugefügt

1. Plugin ist installiert und aktiviert
2. Zuschlagstyp ist aktiv (Admin: WSC Zuschlagstypen)
3. Produkt hat den Tag, der exakt dem Tag-Namen des Typs entspricht
4. Custom Fields wsc_items_per_large_quantity (und ggf. wsc_items_per_small_quantity) sind gesetzt
5. Artikel-Menge erreicht den Schwellwert
6. Cache geleert: bin/console cache:clear

Steuer/Preis stimmt nicht

Prüfe den am Zuschlagstyp hinterlegten Steuersatz – der Zuschlag wird mit diesem berechnet.

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.

Support

• https://www.Web-SEO-Consulting.eu/support

Autor

Christian Säum – Web-SEO-Consulting (WSC)

---

Version: 1.8.1 Shopware: 6.6.x – 6.7.x PHP: 8.2+