Deutsche Version

Back to overview

PDF Invoices: Technical Details

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

This documentation always describes the latest published version.

Invoice creation flow

The invoice is not triggered by an order event. It is created either when the order email is sent or manually in the admin area. Both paths call the same service (InvoiceService.createForOrder).

graph TD
    A["Mail path: order email, missing invoice is created automatically"] --> E["InvoiceService.createForOrder"]
    M["Admin path: Create Invoice (InvoiceController.createInvoice)"] --> E
    E --> N["Assign invoice number"]
    N --> S["Build snapshot (ExtendedOrder.createInvoiceSnapshot)"]
    S --> P["Render PDF (Twig template and Dompdf)"]
    P --> F["Store PDF and compute SHA-256"]
    F --> R["Save record in mmd_pdfinvoice"]

The order inside createForOrder is: check for an existing invoice, assign the number, build the snapshot, create the PDF, store the file, compute the hash, save the record. The number is therefore fixed before the PDF exists.

The admin path ends with the stored PDF. It attaches nothing to an order email and sets no sent status. Attaching and setting the sent status belong only to the mail path in ExtendedEmail.send:

graph TD
    A["Order email is sent (ExtendedEmail.send)"] --> B{"Attachment mode matches recipient?"}
    B -->|"No"| X["Email without invoice"]
    B -->|"Yes"| C{"Invoice exists for the order?"}
    C -->|"Yes"| G["Read PDF from storage and verify hash"]
    C -->|"No"| D{"Auto-generate enabled?"}
    D -->|"No"| X
    D -->|"Yes"| E["InvoiceService.createForOrder (see above)"]
    E --> G
    G --> H["Attach PDF to the email and set sent status"]

Components

Module data

Invoice numbering

Format: {prefix}{year}-{number} with a five-digit number with leading zeros, for example RE-2026-00001.

• The year is the year of creation. There is one row in mmd_pdfinvoice_seq per combination of shop and year.
• With every new year the counter automatically starts at 1 again. There is no setting for a counter that continues across years.
• The counter row is created with the first invoice of the year. The increment is atomic through a single UPDATE using LAST_INSERT_ID(), so parallel requests cannot receive the same number. The method is MySQL-specific.
• The prefix is read from the current setting when the number is generated.

The admin area shows the setting "Reset Numbering Yearly" (mmdPdfInvoiceResetYearly). It has no effect in the code. Numbering always runs per shop and year, whether the option is switched on or off.

PDF file storage

Path: {storage path}/{shop ID}/{year}/{month}/{invoice number}.pdf, relative to the shop directory. In the invoice number every character except letters, digits, - and _ is replaced by _. Year and month come from the invoice date.

On reading, the module compares the file's SHA-256 hash with the value stored in PDF_HASH. If it differs, the file is not delivered until the PDF has been regenerated.

Dompdf keeps its font cache in source/tmp/dompdf. The PDF is created in A4 portrait with the default font DejaVu Sans.

Database

mmd_pdfinvoice

Unique keys: OXORDERID + OXSHOPID (one invoice per order and shop) and INVOICE_NUMBER + OXSHOPID (one invoice number per shop).

mmd_pdfinvoice_seq

The PREFIX column is filled when the row is created. The number itself is always built with the current setting.

Data snapshot

When the invoice is created, the module stores the snapshot in SNAPSHOT_DATA. It is built from the order and contains:

The shop master data and the logo are not part of the snapshot. When a PDF is regenerated they are read as they are now.

Behavior on errors

• Errors while attaching to an order email are logged, the order email is still sent.
• If PDF creation fails during manual creation, the admin area shows an error message and the cause is in the OXID log.
• Tables and storage remain when the module is deactivated.