Anexos de Arquivo

O TCPDF-Next pode incorporar arquivos arbitrários dentro de um documento PDF. O sistema de anexos é gerenciado através de Navigation\FileAttachment e acessado via a API fluente do Document. Os anexos viajam com o PDF — destinatários podem extrair os arquivos incorporados diretamente do visualizador.

Todos os métodos retornam static, então cada chamada pode ser encadeada.

Referência Rápida

Método	Propósito
addFileAttachment()	Incorporar um arquivo no documento PDF

Exemplo Básico

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)

    // Anexar arquivos de suporte
    ->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

Parâmetro	Tipo	Descrição
$file	string	Caminho absoluto para o arquivo a incorporar
$name	string	Nome de exibição no painel de anexos do visualizador (padrão: nome original do arquivo)
$desc	string	Descrição legível do anexo
$mimeType	string	Tipo MIME (auto-detectado se vazio)
$relationship	string	Relação de arquivo associado PDF 2.0 (Data, Source, Alternative, Supplement, Unspecified)

Casos de Uso Comuns

Anexe dados fonte, documentos suplementares ou originais em alta resolução:

$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');

Conformidade PDF/A-3 e PDF/A-4

Os padrões de arquivamento PDF/A-3 e PDF/A-4 permitem arquivos incorporados, tornando anexos essenciais para troca de dados estruturados. O caso de uso mais proeminente é faturamento eletrônico ZUGFeRD / Factur-X, onde um XML de fatura legível por máquina é incorporado junto ao PDF legível por humanos.

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)

    // Anexo de fatura eletrônica 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

Ao mirar PDF/A-3 ou PDF/A-4, defina o parâmetro $relationship para descrever como o anexo se relaciona com o documento. Valores comuns são Data (representação de dados estruturados), Source (arquivo fonte original) e Alternative (representação alternativa).

Metadados do Anexo

Arquivos incorporados carregam metadados que os visualizadores exibem em seus painéis de anexos:

Metadado	Origem
Nome do arquivo	Parâmetro $name (ou nome original do arquivo)
Descrição	Parâmetro $desc
Tipo MIME	Parâmetro $mimeType (auto-detectado se vazio)
Tamanho	Calculado automaticamente do arquivo
Data de modificação	Lido do timestamp do filesystem do arquivo

Dicas

• Anexos aumentam o tamanho do PDF aproximadamente pelo tamanho do arquivo incorporado. Considere comprimir anexos grandes antes de incorporar.
• Adobe Acrobat, Foxit Reader e a maioria dos visualizadores PDF desktop suportam anexos. Visualizadores baseados em navegador tipicamente não expõem o painel de anexos.
• Não há restrição de formato — você pode anexar qualquer tipo de arquivo (CSV, XLSX, XML, PNG, ZIP, etc.).
• Para fluxos de trabalho de faturamento eletrônico, sempre valide o XML contra o schema padrão relevante (ZUGFeRD, Factur-X ou XRechnung) antes de incorporar.