PDF Invoices: Extending

Extension points of the PDF Invoices module for OXID eShop 7.x: chain extensions for Order and Email, order methods for templates and modules, services and exceptions.

Deutsche Version

Back to overview

PDF Invoices: Extending

This documentation always describes the latest published version.

This page is for developers who want to access invoice data from their own modules or templates. The module does not dispatch any events of its own and has no configuration for extensions. The following points are available.

Chain extensions

The module extends two OXID classes through the module chain:

OXID class	Extension	Purpose
`OxidEsales\Eshop\Core\Email`	`Mmd\PdfInvoice\Model\ExtendedEmail`	Attach the invoice to order emails
`OxidEsales\Eshop\Application\Model\Order`	`Mmd\PdfInvoice\Model\ExtendedOrder`	Access to invoice and snapshot

ExtendedEmail

sendOrderEmailToUser(), sendOrderEmailToOwner() and send() are overridden. The two order email methods only remember the order ID and the recipient type; the attachment is added in send() because OXID resets the attachments before that. Your own modules extending the same methods are not affected as long as they call parent::.

ExtendedOrder

The order gets four additional methods:

Method	Return value	Description
`getInvoice()`	`Invoice` or `null`	Invoice of the order, `null` if none exists or the lookup fails
`hasInvoice()`	`bool`	Whether an invoice exists
`getInvoiceNumber()`	`string` or `null`	Invoice number if an invoice exists
`createInvoiceSnapshot()`	`array`	Builds the snapshot from the current order data (see Technical)

createInvoiceSnapshot() does not store anything, it only returns the array. The snapshot is stored when the invoice is created.

Services

The services are registered in OXID's dependency injection container. These are publicly accessible:

Service	Purpose
`Mmd\PdfInvoice\Service\InvoiceServiceInterface`	Create, load and save invoices, regenerate PDFs
`Mmd\PdfInvoice\Service\InvoiceConfigurationInterface`	Read access to the module settings
`Mmd\PdfInvoice\Service\DebugLogger`	Logger that only writes debug messages when debug logging is enabled
`Mmd\PdfInvoice\Repository\InvoiceRepository`	Database access to `mmd_pdfinvoice`

Further interfaces are InvoiceNumberGeneratorInterface, InvoiceStorageInterface and PdfGeneratorInterface. They are used by the InvoiceService.

InvoiceServiceInterface

Method	Description
`createForOrder(Order $order): Invoice`	Creates number, snapshot, PDF and database record. Throws `InvoiceAlreadyExistsException` if an invoice already exists
`getByOrder(string $orderId): ?Invoice`	Invoice for an order ID
`getByNumber(string $invoiceNumber, int $shopId): ?Invoice`	Invoice for an invoice number
`getPdfContent(Invoice $invoice): string`	PDF content from storage, with hash verification
`save(Invoice $invoice): void`	Saves changes (file path, hash, sent status)
`regeneratePdf(Invoice $invoice): void`	Re-creates the PDF from the snapshot and replaces the file

Example in your own module:

use Mmd\PdfInvoice\Service\InvoiceServiceInterface;
use OxidEsales\EshopCommunity\Internal\Container\ContainerFactory;

$service = ContainerFactory::getInstance()
    ->getContainer()
    ->get(InvoiceServiceInterface::class);

$invoice = $service->getByOrder($orderId);

Exceptions

Class	When
`InvoiceAlreadyExistsException`	An invoice already exists for the order (`getExistingInvoice()` returns it)
`InvoiceGenerationException`	The invoice or PDF could not be created, or the hash check failed
`PdfGenerationException`	Dompdf or the template rendering failed
`StorageException`	The PDF file could not be written, read or deleted
`InvoiceNumberException`	The invoice number could not be assigned

All classes are in the namespace Mmd\PdfInvoice\Exception.