Allegati File

TCPDF-Next può incorporare file arbitrari dentro un documento PDF. Il sistema allegati è gestito tramite Navigation\FileAttachment ed è accessibile tramite l'API fluente Document. Gli allegati viaggiano con il PDF — i destinatari possono estrarre i file incorporati direttamente dal loro visualizzatore.

Tutti i metodi restituiscono static, quindi ogni chiamata può essere concatenata.

Riferimento Rapido

Metodo	Scopo
addFileAttachment()	Incorpora un file nel documento PDF

Esempio Base

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)

    // Allega file supporto
    ->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

Parametro	Tipo	Descrizione
$file	string	Percorso assoluto al file da incorporare
$name	string	Nome visualizzato nel pannello allegati visualizzatore (predefinito al filename originale)
$desc	string	Descrizione leggibile umano dell'allegato
$mimeType	string	Tipo MIME (auto-rilevato se vuoto)
$relationship	string	Relazione file associato PDF 2.0 (Data, Source, Alternative, Supplement, Unspecified)

Casi d'Uso Comuni

Allega dati sorgente, documenti supplementari o originali alta risoluzione:

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

Conformità PDF/A-3 e PDF/A-4

Gli standard archivio PDF/A-3 e PDF/A-4 consentono file incorporati, rendendo gli allegati essenziali per scambio dati strutturati. Il caso d'uso più prominente è la fatturazione elettronica ZUGFeRD / Factur-X, dove una fattura XML machine-readable è incorporata accanto al PDF human-readable.

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)

    // Allegato e-invoice 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

Quando puntando a PDF/A-3 o PDF/A-4, imposta il parametro $relationship per descrivere come l'allegato si relaziona al documento. Valori comuni sono Data (rappresentazione dati strutturati), Source (file sorgente originale) e Alternative (rappresentazione alternativa).

Metadata Allegato

I file incorporati trasportano metadata che i visualizzatori mostrano nei loro pannelli allegati:

Metadata	Sorgente
Filename	Parametro $name (o filename originale)
Descrizione	Parametro $desc
Tipo MIME	Parametro $mimeType (auto-rilevato se vuoto)
Dimensione	Calcolato automaticamente dal file
Data modifica	Letto dal timestamp filesystem del file

Suggerimenti

• Gli allegati aumentano la dimensione file PDF di circa la dimensione del file incorporato. Considera di comprimere allegati grandi prima dell'incorporamento.
• Adobe Acrobat, Foxit Reader e la maggior parte dei visualizzatori PDF desktop supportano allegati. I visualizzatori basati browser tipicamente non espongono il pannello allegati.
• Non c'è restrizione formato — puoi allegare qualsiasi tipo file (CSV, XLSX, XML, PNG, ZIP, ecc.).
• Per workflow e-invoicing, valida sempre l'XML contro lo schema standard rilevante (ZUGFeRD, Factur-X o XRechnung) prima dell'incorporamento.