Pièces jointes

TCPDF-Next peut intégrer des fichiers arbitraires dans un document PDF. Le système de pièces jointes est géré via Navigation\FileAttachment et est accessible via l'API fluent de Document. Les pièces jointes voyagent avec le PDF — les destinataires peuvent extraire les fichiers intégrés directement depuis leur lecteur.

Toutes les méthodes retournent static, permettant le chaînage.

Référence rapide

Méthode	Objectif
addFileAttachment()	Intégrer un fichier dans le document PDF

Exemple de base

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Facture #2026-001', newLine: true)
    ->cell(0, 10, 'La feuille de calcul originale est jointe à ce PDF.', newLine: true)

    // Joindre les fichiers support
    ->addFileAttachment('/path/to/invoice-data.xlsx', 'invoice-data.xlsx', 'Données de facture originales')
    ->addFileAttachment('/path/to/zugferd.xml', 'factur-x.xml', 'XML e-facture Factur-X')

    ->save('facture-avec-pieces-jointes.pdf');

addFileAttachment()

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

Paramètre	Type	Description
$file	string	Chemin absolu vers le fichier à intégrer
$name	string	Nom d'affichage dans le panneau de pièces jointes (par défaut le nom de fichier original)
$desc	string	Description lisible de la pièce jointe
$mimeType	string	Type MIME (auto-détecté si vide)
$relationship	string	Relation de fichier associé PDF 2.0 (Data, Source, Alternative, Supplement, Unspecified)

Cas d'usage courants

Joindre des données source, documents supplémentaires ou originaux haute résolution :

$pdf->addFileAttachment('/path/to/report-data.csv', 'report-data.csv', 'Export CSV brut')
    ->addFileAttachment('/path/to/terms.pdf', 'conditions-generales.pdf', 'Conditions générales')
    ->addFileAttachment('/path/to/photo-full.tiff', 'photo-full.tiff', 'Original pleine résolution');

Conformité PDF/A-3 et PDF/A-4

Les normes d'archivage PDF/A-3 et PDF/A-4 permettent les fichiers intégrés, rendant les pièces jointes essentielles pour l'échange de données structurées. Le cas d'usage le plus important est la facturation électronique ZUGFeRD / Factur-X, où une facture XML lisible par machine est intégrée avec le PDF lisible par l'humain.

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setPDFVersion('2.0')
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Facture électronique', newLine: true)
    ->cell(0, 10, 'Ce PDF contient une pièce jointe XML Factur-X.', newLine: true)

    // Pièce jointe e-facture Factur-X / ZUGFeRD
    ->addFileAttachment(
        '/path/to/factur-x.xml',
        'factur-x.xml',
        'Données de facture Factur-X BASIC',
        'text/xml',
        'Data'
    )

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

TIP

Lorsque vous ciblez PDF/A-3 ou PDF/A-4, définissez le paramètre $relationship pour décrire comment la pièce jointe est liée au document. Les valeurs courantes sont Data (représentation de données structurées), Source (fichier source original) et Alternative (représentation alternative).

Métadonnées de pièce jointe

Les fichiers intégrés transportent des métadonnées que les lecteurs affichent dans leurs panneaux de pièces jointes :

Métadonnée	Source
Nom de fichier	Paramètre $name (ou nom de fichier original)
Description	Paramètre $desc
Type MIME	Paramètre $mimeType (auto-détecté si vide)
Taille	Calculée automatiquement depuis le fichier
Date de modification	Lue depuis l'horodatage du fichier système

Conseils

• Les pièces jointes augmentent la taille du fichier PDF d'environ la taille du fichier intégré. Compressez les pièces jointes volumineuses avant l'intégration.
• Adobe Acrobat, Foxit Reader et la plupart des lecteurs PDF de bureau supportent les pièces jointes. Les lecteurs basés sur navigateur n'exposent généralement pas le panneau de pièces jointes.
• Il n'y a pas de restriction de format — vous pouvez joindre n'importe quel type de fichier (CSV, XLSX, XML, PNG, ZIP, etc.).
• Pour les workflows de facturation électronique, validez toujours le XML selon le schéma standard pertinent (ZUGFeRD, Factur-X ou XRechnung) avant l'intégration.