¶ Extended Voucher Rules - OXID eShop 7
Erweiterte Gutschein-Restriktionen für OXID eShop 7 mit Zahlart-, Versandart-, Zeitfenster-, Erstbesteller- und Kombinationsregeln.
Live Demo: Teste alle Plugins für OXID eShop und Shopware von Markus Michalski live — ohne Installation, ohne Risiko. demo.markus-michalski.net
¶ Inhaltsverzeichnis
- Überblick
- Features
- Anforderungen
- Installation
- Update
- Konfiguration
- Das Pending-Voucher-Pattern
- Chain Extensions
- Praxis-Beispiele
- Fehlerbehebung
- Technische Details
- FAQ
- Lizenz
- Support und Changelog
¶ Überblick
Das Modul Extended Voucher Rules (mmd_voucherrules) erweitert die Gutschein-Funktionalität von OXID eShop 7 um fortgeschrittene Restriktionsregeln. Shop-Betreiber können Gutscheine an spezifische Bedingungen knüpfen, während Kunden eine nahtlose Checkout-Erfahrung behalten.
Das Modul löst ein zentrales Problem: OXID bietet von Haus aus nur einfache Gutschein-Regeln (Mindestbestellwert, Benutzergruppe). Zahlart-/Versandart-abhängige Gutscheine, Zeitfenster oder Kombinationssperren fehlen komplett.
Kernkonzept: Gutscheine mit Zahlart-/Versandart-Restriktionen werden nicht abgelehnt, sondern als "ausstehend" gespeichert und automatisch aktiviert, sobald der Kunde die passende Zahlart/Versandart wählt.
¶ Features
| Feature | Beschreibung |
|---|---|
| Zahlart-Restriktion | Gutscheine nur für bestimmte Zahlarten freigeben |
| Versandart-Restriktion | Gutscheine nur für bestimmte Versandarten freigeben |
| Erstbesteller-Beschränkung | Gutscheine nur für Neukunden ohne vorherige Bestellungen |
| Zeitfenster (Happy Hour) | Gültigkeit an Wochentage und Uhrzeiten binden |
| Kombinationsregeln | Blacklist verbotener Gutschein-Kombinationen |
| Max. kombinierbar | Maximale Anzahl gleichzeitig einlösbarer Gutscheine |
| Zahlart-Mindestbestellwert | Unterschiedliche Mindestbestellwerte je Zahlart |
| Versandart-Mindestbestellwert | Unterschiedliche Mindestbestellwerte je Versandart |
| Pending-Voucher-Pattern | Automatische Aktivierung bei passender Zahlart/Versandart |
¶ Anforderungen
| Anforderung | Version | Hinweise |
|---|---|---|
| OXID eShop | 7.x | CE, PE oder EE |
| PHP | >= 8.2 | |
| Composer | 2.x | Für Installation und Updates |
| Lizenz | Erforderlich | Zugang über Packeton |
Private Repositories werden über Packeton verwaltet. Zugangsdaten erhalten Sie nach dem Lizenzkauf.
1. Private Repository hinzufügen:
{
"repositories": [
{
"type": "composer",
"url": "https://packeton.markus-michalski.net"
}
]
}
2. Modul installieren:
composer require mmd/oxid7-voucherrules
3. Modul aktivieren:
vendor/bin/oe-console oe:module:activate mmd_voucherrules
vendor/bin/oe-console oe:cache:clear
cd <shop-root>
git clone <repository-url> source/modules/mmd/voucherrules
vendor/bin/oe-console oe:module:install-configuration source/modules/mmd/voucherrules
vendor/bin/oe-console oe:module:activate mmd_voucherrules
vendor/bin/oe-console oe:cache:clear
¶
¶ Update
composer update mmd/oxid7-voucherrules
vendor/bin/oe-console oe:cache:clear
Vor jedem Update ein Datenbank-Backup erstellen! Die Modul-Tabellen werden bei der Aktivierung automatisch angelegt, aber ein Rollback ist ohne Backup nicht möglich.
¶ Konfiguration
Nach der Aktivierung erscheinen vier neue Tabs in der Gutscheinserie-Verwaltung unter Shopeinstellungen > Gutscheinserien.
¶ Tab 1: Extended Rules
Hier werden die Basis-Restriktionen konfiguriert:
| Einstellung | Typ | Beschreibung |
|---|---|---|
| Zahlart-Restriktion | Multi-Select | Erlaubte Zahlarten (leer = alle) |
| Versandart-Restriktion | Multi-Select | Erlaubte Versandarten (leer = alle) |
| Nur Erstbesteller | Checkbox | Nur für Kunden ohne abgeschlossene Bestellungen |
| Max. kombinierbar | Zahl (0-99) | Maximale Anzahl kombinierter Gutscheine (0 = unbegrenzt) |
Whitelist-Prinzip: Wenn keine Zahlarten/Versandarten ausgewählt sind, gilt der Gutschein für ALLE Zahlarten/Versandarten. Dadurch werden neue Zahlarten nicht versehentlich ausgesperrt.
¶ Tab 2: Time Windows
Zeitfenster für die Gutschein-Gültigkeit:
| Einstellung | Typ | Beschreibung |
|---|---|---|
| Wochentage | Checkboxen (Mo-So) | An welchen Tagen der Gutschein gültig ist |
| Startzeit | HH:MM:SS | Beginn des Zeitfensters |
| Endzeit | HH:MM:SS | Ende des Zeitfensters |
| Aktiv | Checkbox | Zeitfenster aktivieren/deaktivieren |
Mehrere Zeitfenster pro Gutscheinserie möglich (z.B. Mo-Fr 12:00-14:00 + Sa-So ganztägig).
¶ Tab 3: Combinations
Verwaltung verbotener Gutschein-Kombinationen:
- Blacklist: Welche Gutscheinserien dürfen NICHT zusammen verwendet werden
- Hinzufügen: Dropdown mit allen verfügbaren Gutscheinserien
- Löschen: Einzelne Einträge entfernen
Die Blacklist arbeitet symmetrisch: Wenn Serie A nicht mit Serie B kombinierbar ist, gilt das automatisch auch umgekehrt.
¶ Tab 4: Min Order Value
Zahlart- und versandart-spezifische Mindestbestellwerte:
| Bereich | Einstellungen |
|---|---|
| Payment Min-Values | Zahlart + Mindestbestellwert (EUR) |
| Delivery Min-Values | Versandart + Mindestbestellwert (EUR) |
Damit lassen sich z.B. höhere Mindestbestellwerte für Nachnahme oder Rechnungskauf konfigurieren.
¶ Das Pending-Voucher-Pattern
Das Kernkonzept des Moduls: Gutscheine mit Zahlart-/Versandart-Restriktionen können nicht sofort validiert werden, weil der Kunde im Warenkorb noch keine Zahlart gewählt hat.
¶ Zwei Exception-Typen
| Exception | Verhalten | Beispiel |
|---|---|---|
VoucherRuleViolationException |
Permanenter Fehler (rot) - Gutschein wird abgelehnt | Nicht Erstbesteller, außerhalb Zeitfenster, Blacklist |
VoucherRulePendingException |
Ausstehend (gelb/blau) - Gutschein in Session gespeichert | Zahlart noch nicht gewählt, Mindestbestellwert nicht erreicht |
¶ Ablauf
¶ Auto-Aktivierung
¶ Chain Extensions
Das Modul erweitert 6 OXID-Kernklassen:
| Original-Klasse | Erweiterte Klasse | Zweck |
|---|---|---|
Voucher |
Extension\Model\Voucher |
Zentrale Validierung, Pending-Logik |
VoucherSerie |
Extension\Model\VoucherSerie |
Config-Accessor (FirstOrderOnly, MaxCombined) |
Basket |
Extension\Model\Basket |
Auto-Add aus Session, Hint-Generierung |
BasketController |
Extension\Controller\BasketController |
Frontend-Fehlerbehandlung, removePendingVoucher |
ViewConfig |
Extension\Core\ViewConfig |
Template-Daten (Hints, PendingVouchers) |
Order |
Extension\Model\Order |
Cleanup nach Bestellabschluss |
¶ Praxis-Beispiele
¶ Beispiel 1: PayPal-Gutschein
Ziel: 10% Rabatt nur bei Zahlung mit PayPal.
Konfiguration:
- Gutscheinserie anlegen mit 10% Rabatt
- Tab "Extended Rules" > Zahlart-Restriktion: Nur "PayPal" auswählen
- Fertig
Kundenverhalten:
- Kunde gibt Code ein > sieht Hinweis "Gutschein wird angewendet bei Zahlung mit PayPal"
- Kunde wählt PayPal > Gutschein wird automatisch aktiviert
- Kunde wechselt zu Vorkasse > Gutschein wird wieder ausstehend
¶ Beispiel 2: Happy Hour Freitag
Ziel: 15% Rabatt nur freitags zwischen 18:00 und 22:00 Uhr.
Konfiguration:
- Gutscheinserie anlegen mit 15% Rabatt
- Tab "Time Windows" > Neues Zeitfenster:
- Wochentag: Nur "Freitag" ankreuzen
- Startzeit: 18:00:00
- Endzeit: 22:00:00
- Aktiv: Ja
Verhalten:
- Freitag 19:30 > Gutschein wird akzeptiert
- Samstag 10:00 > Fehler: "Gutschein außerhalb des Gültigkeitszeitraums"
¶ Beispiel 3: Stapelschutz
Ziel: Maximal 2 Gutscheine gleichzeitig, und "SOMMER24" darf nicht mit "WINTER24" kombiniert werden.
Konfiguration:
- Bei beiden Gutscheinserien: Tab "Extended Rules" > Max. kombinierbar: 2
- Bei "SOMMER24": Tab "Combinations" > "WINTER24" zur Blacklist hinzufügen
¶ Fehlerbehebung
¶ Gutschein wird nicht akzeptiert
Symptome: Kunde gibt gültigen Code ein, sieht aber eine rote Fehlermeldung.
Prüfen:
- Admin > Gutscheinserie > Sind die Standard-OXID-Regeln erfüllt? (Gültigkeitsdatum, Benutzergruppe, etc.)
- Admin > Gutscheinserie > Tab "Extended Rules": Welche Restriktionen sind aktiv?
- Admin > Tab "Time Windows": Liegt die aktuelle Zeit im Gültigkeitsfenster?
Lösung: Restriktionen anpassen oder Zeitfenster überprüfen.
¶ Ausstehender Gutschein wird nicht automatisch aktiviert
Symptome: Gutschein ist als ausstehend markiert, wird aber bei Zahlart-Auswahl nicht aktiviert.
Prüfen:
- Ist die gewählte Zahlart in der Whitelist der Gutscheinserie enthalten?
- Ist der Mindestbestellwert für diese Zahlart erreicht?
- Cache leeren und erneut testen
Lösung:
vendor/bin/oe-console oe:cache:clear
¶ Modulaktivierung schlägt fehl
Symptome: Fehler bei oe:module:activate mmd_voucherrules.
Prüfen:
- Sind alle Composer-Abhängigkeiten installiert?
- Ist der Namespace korrekt registriert?
Lösung:
composer dump-autoload
vendor/bin/oe-console oe:cache:clear
vendor/bin/oe-console oe:module:activate mmd_voucherrules
Bei anhaltenden Problemen: Modul deaktivieren, Cache leeren, Modul erneut aktivieren.
¶ Kombinations-Blacklist greift nicht
Symptome: Zwei Gutscheine können kombiniert werden, obwohl sie auf der Blacklist stehen.
Prüfen:
- Admin > Gutscheinserie > Tab "Combinations": Ist die Kombination eingetragen?
- Ist der Eintrag bei BEIDEN Serien sichtbar? (symmetrische Blacklist)
Lösung: Blacklist-Eintrag entfernen und neu hinzufügen. Die Zuordnung wird in beiden Richtungen gespeichert.
¶ Technische Details
¶ Modulstruktur
oxid7-voucherrules/
├── src/
│ ├── Controller/Admin/
│ │ ├── VoucherRulesMain.php
│ │ ├── VoucherRulesTimeWindow.php
│ │ ├── VoucherRulesCombination.php
│ │ └── VoucherRulesPaymentMinVal.php
│ ├── Extension/
│ │ ├── Model/ (Voucher, VoucherSerie, Basket, Order)
│ │ ├── Controller/ (BasketController)
│ │ └── Core/ (ViewConfig)
│ ├── Service/
│ │ ├── VoucherValidationService.php
│ │ ├── FirstOrderCheckService.php
│ │ ├── CombinationCheckService.php
│ │ ├── TimeWindowCheckService.php
│ │ └── VoucherRestrictionHintService.php
│ ├── Repository/ (7 Repositories)
│ ├── Exception/
│ │ ├── VoucherRuleViolationException.php
│ │ └── VoucherRulePendingException.php
│ └── Core/
│ └── ModuleEvents.php
├── views/twig/
│ ├── admin/ (4 Admin-Templates)
│ └── extensions/themes/apex/ (Storefront-Override)
├── translations/ (de + en)
├── metadata.php
├── composer.json
└── services.yaml
¶ Architektur
¶ Validierungsflow
¶ Datenbankschema
7 Tabellen mit Präfix mmd_voucherrules_:
| Tabelle | Beziehung | Beschreibung |
|---|---|---|
_config |
1:1 pro Serie | FIRSTORDERONLY (Bool), MAXCOMBINED (Int) |
_payment |
n:m | Whitelist erlaubter Zahlarten |
_delivery |
n:m | Whitelist erlaubter Versandarten |
_timewindow |
1:n | Zeitfenster mit Wochentag-Bitmask (7 Bits: Mo-So), Start-/Endzeit |
_combination |
n:m (self-ref) | Kanonische Blacklist-Paare (A < B alphabetisch) |
_payment_minval |
1:n | Zahlart-spezifische Mindestbestellwerte |
_delivery_minval |
1:n | Versandart-spezifische Mindestbestellwerte |
Alle Tabellen werden bei Modul-Aktivierung automatisch erstellt (CREATE TABLE IF NOT EXISTS). Bei Deaktivierung bleiben die Daten erhalten.
¶ FAQ
Werden bestehende Gutscheine durch das Modul beeinflusst?
Nein. Gutscheine ohne konfigurierte Restriktionen verhalten sich exakt wie vorher. Das Modul erweitert nur, es schränkt nicht ein.
Was passiert, wenn eine neue Zahlart hinzugefügt wird?
Dank Whitelist-Semantik (leer = alle erlaubt) funktionieren bestehende Gutscheine automatisch mit neuen Zahlarten. Nur Gutscheine mit expliziter Zahlart-Whitelist müssen angepasst werden.
Funktioniert das Modul mit der Enterprise Edition?
Ja. Alle Datenbank-Queries filtern nach OXSHOPID, sodass Multi-Shop-Setups korrekt funktionieren.
Können mehrere Zeitfenster pro Gutscheinserie angelegt werden?
Ja. Es können beliebig viele Zeitfenster definiert werden. Der Gutschein ist gültig, wenn mindestens ein aktives Zeitfenster zutrifft.
Was passiert bei Kombinations-Blacklist, wenn der Kunde den zweiten Gutschein zuerst eingibt?
Die Blacklist wird bei jedem Gutschein-Check geprüft. Egal welcher Gutschein zuerst eingegeben wird, die Kombination wird erkannt und verhindert.
¶ Lizenz
Proprietär - Alle Rechte vorbehalten. Lizenz erhältlich über markus-michalski.net.
¶ Support und Changelog
Support: support@markus-michalski.net
Changelog: Siehe CHANGELOG.md
¶ Version 1.0.0 (März 2026)
- Zahlart- und Versandart-Restriktionen
- Erstbesteller-Beschränkung
- Zeitfenster mit Wochentag-Bitmask
- Kombinationsregeln und Max-Combined
- Zahlart- und versandart-spezifische Mindestbestellwerte
- Pending-Voucher-Pattern mit Auto-Aktivierung
- 4 Admin-Tabs für Gutscheinserie
- Deutsche und englische Übersetzungen