Attachments & Metadata

WeasyPrint supports embedding file attachments and XMP metadata in generated PDFs.

Attachments

You can attach files to a PDF by calling addAttachment() on the factory after preparing a source:

$factory->prepareSource('<h1>Invoice</h1>')
  ->addAttachment('/path/to/terms.pdf')
  ->addAttachment('/path/to/receipt.png');

The method is fluent, so you can chain as many attachments as needed.

Relationships

You can optionally specify a relationship type for each attachment, which describes how the attachment relates to the PDF:

$factory->prepareSource('<h1>Invoice</h1>')
  ->addAttachment('/path/to/invoice.xml', relationship: 'Data')
  ->addAttachment('/path/to/terms.pdf', relationship: 'Supplement');

This maps to the --attachment-relationship flag in the WeasyPrint CLI.

Using a Source Object

You can also add attachments via a Source object before passing it to the factory:

use WeasyPrint\Objects\Source;

$source = new Source('<h1>Invoice</h1>');
$source->addAttachment('/path/to/terms.pdf');

$factory->prepareSource($source);

File Validation

Attachment files are validated when the PDF is built. If a file does not exist, an AttachmentNotFoundException is thrown.

XMP Metadata

XMP (Extensible Metadata Platform) metadata can be embedded in the PDF using addXmpMetadata(). This accepts a path to an RDF/XML file:

$factory->prepareSource('<h1>Invoice</h1>')
  ->addXmpMetadata('/path/to/metadata.xml');

Like attachments, the method is fluent and can be called multiple times:

$factory->prepareSource('<h1>Invoice</h1>')
  ->addXmpMetadata('/path/to/facturx.xml')
  ->addXmpMetadata('/path/to/additional-metadata.xml');

EU E-Invoicing

XMP metadata is particularly useful for EU e-invoicing standards like ZUGFeRD and Factur-X, where a conforming PDF must include structured metadata alongside an XML invoice attachment:

$factory->prepareSource($invoiceHtml)
  ->addAttachment('/path/to/factur-x.xml', relationship: 'Data')
  ->addXmpMetadata('/path/to/factur-x-metadata.xml');