Вложенные файлы

TCPDF-Next может встраивать произвольные файлы внутрь PDF-документа. Система вложений управляется через Navigation\FileAttachment и доступна через fluent API класса Document. Вложения сопровождают PDF — получатели могут извлечь встроенные файлы непосредственно из просмотрщика.

Все методы возвращают static, поэтому каждый вызов может быть объединён в цепочку.

Краткий справочник

Метод	Назначение
addFileAttachment()	Встроить файл в PDF-документ

Базовый пример

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)

    // Прикрепление сопроводительных файлов
    ->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

Параметр	Тип	Описание
$file	string	Абсолютный путь к встраиваемому файлу
$name	string	Отображаемое имя в панели вложений просмотрщика (по умолчанию — оригинальное имя файла)
$desc	string	Человекочитаемое описание вложения
$mimeType	string	MIME-тип (автоопределяется, если пусто)
$relationship	string	Связь ассоциированного файла PDF 2.0 (Data, Source, Alternative, Supplement, Unspecified)

Типичные сценарии использования

Прикрепление исходных данных, дополнительных документов или оригиналов высокого разрешения:

$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 и PDF/A-4

Стандарты архивирования PDF/A-3 и PDF/A-4 разрешают встроенные файлы, что делает вложения существенными для структурированного обмена данными. Наиболее заметный вариант использования — электронное выставление счетов ZUGFeRD / Factur-X, где машиночитаемый XML-счёт встраивается рядом с человекочитаемым 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
    ->addFileAttachment(
        '/path/to/factur-x.xml',
        'factur-x.xml',
        'Factur-X BASIC invoice data',
        'text/xml',
        'Data'
    )

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

TIP

При ориентации на PDF/A-3 или PDF/A-4 установите параметр $relationship для описания связи вложения с документом. Распространённые значения: Data (структурное представление данных), Source (исходный файл) и Alternative (альтернативное представление).

Метаданные вложений

Встроенные файлы несут метаданные, которые просмотрщики отображают в панели вложений:

Метаданные	Источник
Имя файла	Параметр $name (или оригинальное имя файла)
Описание	Параметр $desc
MIME-тип	Параметр $mimeType (автоопределяется, если пусто)
Размер	Рассчитывается автоматически из файла
Дата модификации	Читается из временной метки файловой системы

Советы

• Вложения увеличивают размер PDF примерно на размер встроенного файла. Рассмотрите сжатие больших вложений перед встраиванием.
• Adobe Acrobat, Foxit Reader и большинство настольных PDF-просмотрщиков поддерживают вложения. Браузерные просмотрщики обычно не показывают панель вложений.
• Ограничений на формат нет — можно прикреплять файлы любого типа (CSV, XLSX, XML, PNG, ZIP и т.д.).
• Для рабочих процессов электронного выставления счетов всегда валидируйте XML по соответствующей схеме стандарта (ZUGFeRD, Factur-X или XRechnung) перед встраиванием.