English Version

Zurück zur Übersicht

Extended Voucher Rules: Technische Details

Live Demo: Teste dieses und weitere Plugins live — ohne Installation, ohne Risiko: demo.markus-michalski.net

Modul im Überblick

Validierungsreihenfolge

Die zentrale Prüfung liegt in VoucherValidationService::validate(). Sie wird aus der erweiterten Voucher-Klasse aufgerufen, nachdem die Standardprüfung von OXID bestanden wurde. Die Regeln laufen in dieser Reihenfolge, die erste ausgelöste Ausnahme beendet die Prüfung:

1. Zahlart-Beschränkung
2. Versandart-Beschränkung
3. Erstbesteller
4. Zeitfenster
5. Kombinationen (Höchstzahl, dann Sperrliste)
6. Mindestbestellwert pro Zahlart
7. Mindestbestellwert pro Versandart

Folge der Reihenfolge: Solange eine Zahl- oder Versandart-Regel noch aussteht, werden die Regeln danach (zum Beispiel das Zeitfenster) noch nicht ausgewertet.

graph TD
    A[VoucherValidationService.validate] --> B[Zahlart-Beschränkung]
    B --> C[Versandart-Beschränkung]
    C --> D[Erstbesteller]
    D --> E[Zeitfenster]
    E --> F[Kombinationen]
    F --> G[Mindestbestellwert Zahlart]
    G --> H[Mindestbestellwert Versandart]
    H --> I[Alle Regeln bestanden]
    B -->|Zahlart fehlt oder passt nicht| P[VoucherRulePendingException]
    C -->|Versandart fehlt oder passt nicht| P
    G -->|Zahlart fehlt oder Wert nicht erreicht| P
    H -->|Versandart fehlt oder Wert nicht erreicht| P
    D -->|nicht Erstbesteller| V[VoucherRuleViolationException]
    E -->|außerhalb des Fensters| V
    F -->|gesperrt oder Höchstzahl| V

Verhalten je Regel

Der Wochentag wird mit date('N') ermittelt, die Uhrzeit mit CURTIME() der Datenbank. Die Fensterprüfung ist CURTIME() BETWEEN STARTTIME AND ENDTIME, bei Eingabe als HH:MM endet ein Fenster also bei Sekunde 00.

Vormerk-Mechanik

Ein Gutschein mit offener Bedingung löst eine VoucherRulePendingException aus. Die Klasse Extension\Model\Voucher fängt sie, merkt die Gutscheinnummer vor und legt einen Hinweis ab. Die Ausnahme wird erneut geworfen, damit OXID keinen Rabatt anrechnet. Eine VoucherRuleViolationException entfernt die Vormerkung und weist den Gutschein ab. Beide Ausnahmen erweitern die OXID-VoucherException.

Gespeichert wird in der Session unter zwei Schlüsseln: mmd_voucherrules_pending (Liste der Gutscheinnummern) und mmd_voucherrules_hints (Hinweise mit Schlüssel und Mindestwert). Gelesen werden die Session-Werte paymentid und sShipSet.

graph TD
    A[Kunde wählt Zahlart oder Versandart] --> B[Basket.calculateBasket]
    B --> C{Vormerkungen in der Session?}
    C -->|Nein| D[Normale Berechnung]
    C -->|Ja| E[addVoucher je vorgemerkter Nummer]
    E --> F{Ergebnis}
    F -->|bestanden| G[Gutschein aktiv, Vormerkung entfernt]
    F -->|weiter offen| H[bleibt vorgemerkt]
    F -->|endgültig ungültig| I[Vormerkung entfernt]

Die Auto-Aktivierung läuft nur, wenn in der Session eine Zahl- oder eine Versandart gesetzt ist. Nach Order::finalizeOrder() werden Vormerkungen, Hinweise sowie paymentid und sShipSet gelöscht. Bei leerem Warenkorb (Basket::calculateBasket()) werden nur Vormerkungen und Hinweise gelöscht.

Erweiterte Shop-Klassen

Admin-Controller

Die Tabs hängen unter dem Menüpunkt mxvouchers (Hauptmenü mxshopsett). Alle schreibenden Aktionen prüfen die Session-Challenge, Löschen und Ändern prüft zusätzlich Serie und Shop des Eintrags.

Services und Erweiterbarkeit

Die Services und Repositories sind im Symfony-Container als öffentlich markiert (services.yaml) und können über die ContainerFactory bezogen werden: VoucherValidationService, FirstOrderCheckService, TimeWindowCheckService, CombinationCheckService, VoucherRestrictionHintService sowie die Repositories VoucherRulesConfigRepository, PaymentRestrictionRepository, DeliveryRestrictionRepository, TimeWindowRepository, CombinationRepository, PaymentMinValueRepository und DeliveryMinValueRepository. Ein dokumentiertes Erweiterungs-API oder Events gibt es nicht.

Erweiterung der Templates

Für das Theme Apex liefert das Modul zwei Template-Erweiterungen mit:

• layout/base.html.twig bindet das Stylesheet css/voucherrules.css im Block base_style ein.
• page/checkout/inc/summary_sidebar.html.twig ergänzt den Block checkout_basketcontents_grandtotal um die Hinweisbox. Sie nutzt oViewConf.getPendingVouchers() und oViewConf.getVoucherRulesHints(), der Entfernen-Link ruft index.php?cl=basket&fnc=removePendingVoucher mit voucherNr und Session-Token auf.

Für andere Themes kann dasselbe Muster in der Checkout-Zusammenfassung des Themes umgesetzt werden.

Datenbanktabellen

Sieben Tabellen mit dem Präfix mmd_voucherrules_, alle mit OXSHOPID, die Gutscheinserie steht in OXVOUCHERSERIEID:

Die Tabellen werden bei der Aktivierung mit CREATE TABLE IF NOT EXISTS angelegt. Bei der Deaktivierung bleiben die Daten erhalten.