PHPackages                             mahdiabderraouf/facturx-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PDF & Document Generation](/categories/documents)
4. /
5. mahdiabderraouf/facturx-php

ActiveLibrary[PDF & Document Generation](/categories/documents)

mahdiabderraouf/facturx-php
===========================

A PHP package for managing Factur-x/ZUGFeRD compliant PDF invoices

v1.2.0(1mo ago)2680MITPHPPHP >=8.2 <8.6CI passing

Since Dec 21Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/mahdiabderraouf/facturx-php)[ Packagist](https://packagist.org/packages/mahdiabderraouf/facturx-php)[ Docs](https://github.com/mahdiabderraouf/facturx-php)[ RSS](/packages/mahdiabderraouf-facturx-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (8)Versions (13)Used By (0)

Factur-X PHP
============

[](#factur-x-php)

A PHP library for managing Factur-x/ZUGFeRD compliant PDF invoices.

Table of Contents
-----------------

[](#table-of-contents)

- [Factur-X PHP](#factur-x-php)
    - [Table of Contents](#table-of-contents)
    - [Features](#features)
    - [Requirements](#requirements)
    - [Installation](#installation)
        - [Using composer](#using-composer)
    - [Documentation](#documentation)
    - [Usage](#usage)
        - [Generate minimum profile XML](#generate-minimum-profile-xml)
        - [Validate XML against XSD](#validate-xml-against-xsd)
        - [Generate a Factur-X PDF](#generate-a-factur-x-pdf)
        - [Parse Factur-X PDF](#parse-factur-x-pdf)
    - [Bug reports](#bug-reports)
    - [Contributions](#contributions)
    - [Roadmap](#roadmap)

---

Features
--------

[](#features)

- **XML generation:** Generate Factur-X XML file from an `Invoice` object, supports `minimum`, `basicwl` and `basic` profiles.
- **PDF generation:** Generate PDF-A3b Factur-X invoice from a given PDF file and a generated/provided XML file.
- **XML validation:** Validates Factur-X XML against the offical Extension Schema Definition (XSD).
- **Parsing:** Extract XML file from a Factur-X.

---

Requirements
------------

[](#requirements)

- PHP version: `>= 8.2`
- [poppler-utils](https://tracker.debian.org/pkg/poppler) for XML extraction

---

Installation
------------

[](#installation)

### Using composer

[](#using-composer)

```
composer require mahdiabderraouf/facturx-php
```

---

Documentation
-------------

[](#documentation)

The full documentation can be found [here](../../wiki).

---

Usage
-----

[](#usage)

Here are some quick examples of usage. For advanced usage please refer to the [documentation](../../wiki)

### Generate minimum profile XML

[](#generate-minimum-profile-xml)

```
use MahdiAbderraouf\FacturX\Builder;
use MahdiAbderraouf\FacturX\Enums\Profile;
use MahdiAbderraouf\FacturX\Models\Invoice;

// Create an invoice object from an array or you can use constructor instead (new Invoice (...))
$invoice = Invoice::createFromArray([
    'profile' => Profile::MINIMUM,
    'number' => 'F-202400001',
    'typeCode' => InvoiceTypeCode::COMMERCIAL_INVOICE,
    'issueDate' => DateTime::createFromFormat('Y-m-d', '2024-12-02'),
    'totalAmountWithoutVAT' => 80.00,
    'totalVATAmount' => 20.00,
    'totalAmountWithVAT' => 100.00,
    'amountDueForPayment' => 22.25,
    'buyer' => [
        'name' => 'Buyer NAME',
        'address' => [
            'countryCode' => 'FR',
        ],

        // optional
        'buyerReference' => 'BUYER-0001',
        'legalRegistrationIdentifier' => 'BUYER-SIRET',
        // Precise the legal registration scheme identifier if different from SIRET
        'schemeIdentifier' => SchemeIdentifier::SIREN,
    ],
    'seller' => [
        'name' => 'Seller NAME',
        'vatIdentifier' => 'FR12345678901',
        'address' => [
            'countryCode' => 'FR',
        ],

        // optional
        'legalRegistrationIdentifier' => 'SELLER-SIRET',
    ],

    // optional
    'businessProcessType' => 'A2', // default A1
    'purchaseOrderReference' => 'PO-202400005',
    'currencyCode' => 'EUR', // default EUR
    'vatCurrency' => 'USD', // default EUR
]);

$xml = $invoice->toXml();
// Or
$xml = Builder::build($invoice);
```

### Validate XML against XSD

[](#validate-xml-against-xsd)

Validate Factur-X XML against XSD. The XML source can be either a PDF file path, an XML file path or an XML string.

```
use MahdiAbderraouf\FacturX\Enums\Profile;
use MahdiAbderraouf\FacturX\Exceptions\InvalidXmlException;
use MahdiAbderraouf\FacturX\Exceptions\UnableToExtractXmlException;
use MahdiAbderraouf\FacturX\Validator;

$profile = Profile::MINIMUM;

// PDF path, XML path or XML string
$source = '/path/to/invoice.pdf';

try {
    Validator::validate(
        $source,

        // Validate against a specific profile, or auto-detect it from the XML.
        Profile::EN16931,
    );
} catch (UnableToExtractXmlException $e) {
    // Failed to extract XML from given PDF
    $message = $e->getMessage();
} catch (InvalidXmlException $e) {
    // array of LibXMLError
    $errors = $e->getErrors();
}

// Or simply check if its valid or not
$isValid = Validator::isValid($source);
```

### Generate a Factur-X PDF

[](#generate-a-factur-x-pdf)

Using the static method `Generator::generate` you can embed an XML into a PDF file to generate a Factur-X file.

To ensure the integrity of every Factur-X file, the XML is validated before being embedded, so there is no need to validate it beforehand.

**Important:** The input PDF must be PDF/A-3b compliant as required by the Factur-X specification. This library does not convert PDFs to PDF/A-3b.

Please note about attachment relationship:

- The only relationships that can be used for the XML file are `Data`, `Source` and `Alternative`.
- In Germany the only relationship allowed is `Alternative`.
- For profiles `minimum` and `basicwl` only the relationship `Data` is allowed.
- It is not recommanded to use the relationship `UNSPECIFIED` when adding additional attachments.

If you are generating invoices in Germany, the profiles `minimum` and `basicwl` are not considered legally as an invoice since they don't contain enough information. Same rule will be applied in France in the future so you should be using at least the `basic` profile.

```
use MahdiAbderraouf\FacturX\Enums\Profile;
use MahdiAbderraouf\FacturX\Exceptions\InvalidXmlException;
use MahdiAbderraouf\FacturX\Generator;

$profile = Profile::BASIC;
$invoice = Invoice::createFromArray([...]);

try {
    $pdfString = Generator::generate(
        // path or PDF string
        '/path/to/Invoice.pdf',
        // Invoice, XML string or path
        $invoice,

        // optional
        AttachmentRelationship::DATA, // default one
        'outputPath.pdf',
        Profile::BASIC, // validates against a specific profile
        // add more attachments if needed
        [
            [
                'file' => 'extra_file.txt',
                // optional
                'filename' => 'Extra file name', // Defaults to the given file name
                'relationship' => AttachmentRelationship::SUPPLEMENT, // Defaults to AttachmentRelationship::UNSPECIFIED when not present
                'description' => 'This is some extra file description',
            ]
        ]
    );
} catch (InvalidXmlException $e) {
    $errors = $e->getErrors();
}
```

### Parse Factur-X PDF

[](#parse-factur-x-pdf)

Parse a Factur-X PDF file, the parser will look by default for files `factur-x.xml` and `zugferd-invoice.xml`.

Please note that the filename `zugferd-invoice.xml` is not used since the version 2.3 of ZUGFeRD. You can specify the files you want to search for

```
use MahdiAbderraouf\FacturX\Enums\XmlFilename;
use MahdiAbderraouf\FacturX\Exceptions\UnableToExtractXmlException;
use MahdiAbderraouf\FacturX\Parser;

// PDF path
$pdf = '/path/to/invoice.pdf';

try {
    // this will look for 'factur-x.xml' or 'zugferd-invoice.xml' files inside the given PDF
    $xml = Parser::getXml(
        $pdf,
        XmlFilename::FACTUR_X, // look only for 'factur-x.xml'
    );
} catch (UnableToExtractXmlException $e) {
    // This probably means that the file is not Factur-X
    $message = $e->getMessage();
}
```

---

Bug reports
-----------

[](#bug-reports)

Create an issue using the bug report template.

---

Contributions
-------------

[](#contributions)

Contributions are welcome, here are some guidelines:

- Code must be PSR-12
- Provide an explanation of the changes
- Provide the reason for the changes
- If needed, update the documentation and provide an example.

---

Roadmap
-------

[](#roadmap)

- Add support for generating `en16931` and `extended` profiles
- Factur-X parsing: parse a Factur-X file to an `Invoice` object.

###  Health Score

49

—

FairBetter than 95% of packages

Maintenance90

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~57 days

Recently: every ~112 days

Total

9

Last Release

49d ago

Major Versions

v0.0.4 → v1.0.02024-12-30

PHP version history (3 changes)v0.0.1-betaPHP >=8.1

v1.1.0PHP >=8.2 <=8.5

v1.2.0PHP >=8.2 <8.6

### Community

Maintainers

![](https://www.gravatar.com/avatar/dfa0cb2c2c8847103a207342481b168cd63449e13625b3ae27fa67e02feebe4c?d=identicon)[mahdi.abderraouf@outlook.com](/maintainers/mahdi.abderraouf@outlook.com)

---

Top Contributors

[![mahdiabderraouf](https://avatars.githubusercontent.com/u/44200782?v=4)](https://github.com/mahdiabderraouf "mahdiabderraouf (75 commits)")

---

Tags

e-invoicefactur-xpdfphpzugferd

###  Code Quality

Static AnalysisRector

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/mahdiabderraouf-facturx-php/health.svg)

```
[![Health](https://phpackages.com/badges/mahdiabderraouf-facturx-php/health.svg)](https://phpackages.com/packages/mahdiabderraouf-facturx-php)
```

###  Alternatives

[mpdf/mpdf

PHP library generating PDF files from UTF-8 encoded HTML

4.7k77.1M493](/packages/mpdf-mpdf)[webklex/laravel-pdfmerger

Generic PDF merger for Laravel

1422.6M2](/packages/webklex-laravel-pdfmerger)[jurosh/pdf-merge

PHP PDF Merger

1522.2M5](/packages/jurosh-pdf-merge)[creagia/laravel-sign-pad

Laravel package for of E-Signature with Signature Pad and Digital Certified Sign with TCPDF

54097.2k](/packages/creagia-laravel-sign-pad)[setasign/fpdi-protection

A FPDI compatible version of the FPDF\_Protection script.

324.3M2](/packages/setasign-fpdi-protection)[binarystash/pdf-watermarker

Watermark or stamp PDF documents

8260.6k](/packages/binarystash-pdf-watermarker)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)