File Attachments

TCPDF-Next can embed arbitrary files inside a PDF document. The attachment system is managed through Navigation\FileAttachment and is accessed via the Document fluent API. Attachments travel with the PDF — recipients can extract the embedded files directly from their viewer.

All methods return static, so every call can be chained.

Quick Reference

Method	Purpose
addFileAttachment()	Embed a file into the PDF document

Basic Example

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Invoice #2026-001', newLine: true)
    ->cell(0, 10, 'The original spreadsheet is attached to this PDF.', newLine: true)

    // Attach supporting files
    ->addFileAttachment('/path/to/invoice-data.xlsx', 'invoice-data.xlsx', 'Original invoice data')
    ->addFileAttachment('/path/to/zugferd.xml', 'factur-x.xml', 'Factur-X e-invoice XML')

    ->save('invoice-with-attachments.pdf');

addFileAttachment()

$pdf->addFileAttachment(
    string $file,
    string $name = '',
    string $desc = '',
    string $mimeType = '',
    string $relationship = 'Unspecified'
): static

Parameter	Type	Description
$file	string	Absolute path to the file to embed
$name	string	Display name in the viewer's attachment panel (defaults to the original filename)
$desc	string	Human-readable description of the attachment
$mimeType	string	MIME type (auto-detected if empty)
$relationship	string	PDF 2.0 associated file relationship (Data, Source, Alternative, Supplement, Unspecified)

Common Use Cases

Attach source data, supplementary documents, or high-resolution originals:

$pdf->addFileAttachment('/path/to/report-data.csv', 'report-data.csv', 'Raw CSV export')
    ->addFileAttachment('/path/to/terms.pdf', 'terms-and-conditions.pdf', 'Terms & Conditions')
    ->addFileAttachment('/path/to/photo-full.tiff', 'photo-full.tiff', 'Full-resolution original');

PDF/A-3 and PDF/A-4 Compliance

The PDF/A-3 and PDF/A-4 archival standards allow embedded files, making attachments essential for structured data exchange. The most prominent use case is ZUGFeRD / Factur-X electronic invoicing, where a machine-readable XML invoice is embedded alongside the human-readable PDF.

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setPDFVersion('2.0')
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Electronic Invoice', newLine: true)
    ->cell(0, 10, 'This PDF contains a Factur-X XML attachment.', newLine: true)

    // Factur-X / ZUGFeRD e-invoice attachment
    ->addFileAttachment(
        '/path/to/factur-x.xml',
        'factur-x.xml',
        'Factur-X BASIC invoice data',
        'text/xml',
        'Data'
    )

    ->save('e-invoice.pdf');

TIP

When targeting PDF/A-3 or PDF/A-4, set the $relationship parameter to describe how the attachment relates to the document. Common values are Data (structured data representation), Source (original source file), and Alternative (alternative representation).

Attachment Metadata

Embedded files carry metadata that viewers display in their attachment panels:

Metadata	Source
Filename	$name parameter (or original filename)
Description	$desc parameter
MIME type	$mimeType parameter (auto-detected if empty)
Size	Calculated automatically from the file
Modification date	Read from the file's filesystem timestamp

Tips

• Attachments increase PDF file size by roughly the size of the embedded file. Consider compressing large attachments before embedding.
• Adobe Acrobat, Foxit Reader, and most desktop PDF viewers support attachments. Browser-based viewers typically do not expose the attachment panel.
• There is no format restriction — you can attach any file type (CSV, XLSX, XML, PNG, ZIP, etc.).
• For e-invoicing workflows, always validate the XML against the relevant standard schema (ZUGFeRD, Factur-X, or XRechnung) before embedding.