Zugferd Laravel Package

Technical Evaluation

Architecture fit. horstoeko/zugferd is a pure-PHP domain library distributed via Composer that generates and parses ZUGFeRD, Factur-X, and XRechnung documents. It is not a framework-coupled package — it sits naturally at the boundary between order/accounting data and outbound compliant invoice artifacts. In a Laravel codebase this maps cleanly to a dedicated "InvoicingCompliance" or "Billing" bounded context, with the library consumed behind a thin service wrapper so vendor types never leak into Eloquent models or controllers. It does not own persistence, queuing, or transport, so it composes well with existing Laravel conventions (jobs, events, storage disks).

Integration feasibility. Composer install with PSR-4 autoloading and likely Laravel package auto-discovery. The public surface is a builder-style API (invoice header, seller/buyer parties, line items, tax breakdown, payment terms) plus a reader for inbound documents. The major integration variable is output format: XRechnung is standalone XML (CII or UBL) with no PDF dependency, whereas ZUGFeRD/Factur-X require PDF/A-3 embedding, which pulls in a PDF renderer (mPDF/TCPDF/Dompdf) and possibly Ghostscript and an ICC profile. That dependency chain is the main feasibility question, not the library itself.

Technical risk.

• Standards churn. KoSIT publishes XRechnung releases roughly twice yearly and the ZUGFeRD/Factur-X alignment evolves. A pinned library version can silently fall behind a mandated schema.
• Profile coverage. ZUGFeRD defines MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED, and XRECHNUNG profiles; not every profile is equally exercised. Confirm what is actually supported before committing.
• PDF/A-3 conformance. Embedding XML in PDF/A-3 is notoriously finicky (fonts, ICC profiles, metadata). This is the highest-probability source of production failures.
• Bus factor. 441 stars and an active release cadence are healthy signals, but this is a small-maintainer OSS project. The 2026-10-20 release date suggests active development; still, plan for the possibility of a fork.
• Validation gap. Producing XML is not the same as producing accepted XML. Local XSD/Schematron validation and a real receiver-side test are separate workstreams.

Key questions.

1. Which profiles and which XRechnung/KoSIT versions are supported today, and what is the upgrade policy when a new release drops?
2. Is a PDF renderer bundled, optional, or required for ZUGFeRD/Factur-X — and which one is tested?
3. Does the package validate against XSD/Schematron, or only serialize?
4. Does it support both CII and UBL syntaxes for XRechnung?
5. Can it read/parse inbound e-invoices for accounts-payable workflows, or is it generation-only?
6. What is the supported PHP and Laravel version matrix, and is auto-discovery registered?
7. Are there canonical example fixtures per profile we can turn into regression tests?

Integration Approach

Stack fit. Target PHP 8.1+ and Laravel 10–12. Add as a Composer dependency, register the service provider (auto-discovery if available), and wrap the library in a ComplianceInvoiceService that accepts domain DTOs and returns a persisted artifact record (XML path, PDF path, profile, schema version, hash). Keep the library out of controllers entirely.

Migration path. Start narrow and low-risk: generate XRechnung XML only (no PDF) for the German B2G/public-sector segment. This validates the data model, tax semantics, and receiver acceptance with the smallest dependency footprint. Only after that is stable, add ZUGFeRD/Factur-X PDF/A-3 embedding for B2B scenarios. Persist every generated document as an immutable artifact with a hash and the library/schema version used, so audit and re-issuance are possible.

Compatibility. Verify: PHP minor version support, PDF renderer compatibility (mPDF and TCPDF have different PHP 8.x support stories), whether the library emits both CII and UBL, and whether Laravel auto-discovery works or manual registration is needed. Confirm behavior when optional fields (discounts, surcharges, multiple tax rates, reverse charge) are present — these are the common schema-validation breakers.

Sequencing.

1. Legal/finance sign-off on target profiles and standards versions per customer segment.
2. Technical spike: one hard-coded invoice rendered end-to-end and validated against the KoSIT validator and a real receiver.
3. Wrap the library in a service + queueable generation job; add artifact storage and audit metadata.
4. Build a regression corpus (one fixture per profile and edge case) in CI.
5. Add inbound parsing for AP only if the business needs it.
6. Roll out by segment (B2G XML → B2B PDF) with a feature flag.

Operational Impact

Maintenance. Pin to a tested minor version; track upstream releases and KoSIT/ZUGFeRD publication calendars. Budget a quarterly review of schema versions and a defined upgrade playbook. Store the library version and schema version on every generated artifact so historical documents remain reproducible.

Support. Community support via GitHub issues; no commercial SLA. Mitigate with an internal test corpus, a documented fallback export path (manual invoice generation), and a fork strategy that keeps the wrapper interface stable so swapping implementations is a contained change.

Scaling. XML generation is CPU-light and trivially queueable. PDF/A-3 rendering is the heavier operation — offload to a dedicated queue with concurrency limits to avoid starving request workers. Storage grows meaningfully: German and French retention rules imply 8–10 year retention of PDFs, so plan object-storage lifecycle policies and per-profile document sizes early.

Failure modes. Schema-validation failures on edge cases (zero-rated lines, multiple tax categories, rounding and discount rules); PDF/A-3 font/ICC/metadata embedding failures; receiver-side rejections that local validation did not catch; silent schema drift when a new KoSIT release lands; and builder misuse producing structurally valid but semantically wrong invoices (wrong tax category code, wrong profile). The last is the most dangerous because it passes validation but is rejected downstream.

Ramp-up. Any PHP developer can be productive with the builder API in days; the real learning curve is e-invoicing domain knowledge — profiles, tax category codes, Peppol vs. XRechnung semantics, and PDF/A-3 constraints. Pair engineering with a compliance/finance owner, and use the package's examples plus the CI regression corpus as the living documentation.