Deutsche Version

Back to overview

Extended Voucher Rules: Technical Details

Live Demo: Try this and other plugins live — no installation, no risk: demo.markus-michalski.net

Module at a glance

Validation order

The central check lives in VoucherValidationService::validate(). It is called from the extended Voucher class after OXID's standard check has passed. The rules run in this order, and the first exception thrown ends the check:

1. Payment restriction
2. Delivery restriction
3. First order
4. Time window
5. Combinations (maximum, then block list)
6. Minimum order value per payment method
7. Minimum order value per delivery method

Consequence of the order: as long as a payment or delivery rule is still pending, the rules after it (for example the time window) are not evaluated yet.

graph TD
    A[VoucherValidationService.validate] --> B[Payment restriction]
    B --> C[Delivery restriction]
    C --> D[First order]
    D --> E[Time window]
    E --> F[Combinations]
    F --> G[Min order value payment]
    G --> H[Min order value delivery]
    H --> I[All rules passed]
    B -->|payment missing or not matching| P[VoucherRulePendingException]
    C -->|delivery missing or not matching| P
    G -->|payment missing or value not reached| P
    H -->|delivery missing or value not reached| P
    D -->|not a first order| V[VoucherRuleViolationException]
    E -->|outside the window| V
    F -->|blocked or maximum| V

Behaviour per rule

The weekday is determined with date('N'), the time of day with the database's CURTIME(). The window check is CURTIME() BETWEEN STARTTIME AND ENDTIME, so a window entered as HH:MM ends at second 00.

Reservation mechanism

A voucher with an open condition raises a VoucherRulePendingException. The class Extension\Model\Voucher catches it, remembers the voucher number and stores a hint. The exception is re-thrown so that OXID applies no discount. A VoucherRuleViolationException removes the reservation and rejects the voucher. Both exceptions extend OXID's VoucherException.

Data is stored in the session under two keys: mmd_voucherrules_pending (list of voucher numbers) and mmd_voucherrules_hints (hints with key and minimum value). The session values paymentid and sShipSet are read.

graph TD
    A[Customer selects payment or delivery method] --> B[Basket.calculateBasket]
    B --> C{Reservations in the session?}
    C -->|No| D[Normal calculation]
    C -->|Yes| E[addVoucher per reserved number]
    E --> F{Result}
    F -->|passed| G[Voucher active, reservation removed]
    F -->|still open| H[stays reserved]
    F -->|permanently invalid| I[Reservation removed]

Auto-activation only runs if a payment or delivery method is set in the session. After Order::finalizeOrder(), reservations, hints as well as paymentid and sShipSet are deleted. With an empty basket (Basket::calculateBasket()), only reservations and hints are deleted.

Extended shop classes

Admin controllers

The tabs are attached to the menu item mxvouchers (main menu mxshopsett). All writing actions check the session challenge; deleting and changing additionally verify the series and shop of the entry.

Services and extensibility

The services and repositories are marked public in the Symfony container (services.yaml) and can be fetched through the ContainerFactory: VoucherValidationService, FirstOrderCheckService, TimeWindowCheckService, CombinationCheckService, VoucherRestrictionHintService as well as the repositories VoucherRulesConfigRepository, PaymentRestrictionRepository, DeliveryRestrictionRepository, TimeWindowRepository, CombinationRepository, PaymentMinValueRepository and DeliveryMinValueRepository. There is no documented extension API and no events.

Template extension

For the Apex theme the module ships two template extensions:

• layout/base.html.twig includes the stylesheet css/voucherrules.css in the block base_style.
• page/checkout/inc/summary_sidebar.html.twig adds the hint box to the block checkout_basketcontents_grandtotal. It uses oViewConf.getPendingVouchers() and oViewConf.getVoucherRulesHints(); the remove link calls index.php?cl=basket&fnc=removePendingVoucher with voucherNr and the session token.

For other themes the same pattern can be implemented in the theme's checkout summary.

Database tables

Seven tables with the prefix mmd_voucherrules_, all with OXSHOPID; the voucher series is stored in OXVOUCHERSERIEID:

The tables are created on activation with CREATE TABLE IF NOT EXISTS. Data is kept on deactivation.