Migrer depuis TCPDF

Ce guide vous accompagne dans la migration d'un projet existant de TCPDF legacy (tecnickcom/tcpdf) vers TCPDF-Next. TCPDF-Next est une réécriture complète et non un remplacement direct, mais le processus de migration est systématique et bien défini.

Différences clés

Fonctionnalité	TCPDF (Legacy)	TCPDF-Next
Version PHP	5.3+	8.5+
Version PDF	PDF 1.7	PDF 2.0
Architecture	Classe monolithique unique (~27 000 lignes)	17 espaces de noms modulaires, 142 classes
Style API	Procédural, méthodes PascalCase	Constructeur fluide, méthodes camelCase
Sécurité de type	Pas de types	declare(strict_types=1), enums, readonly
Analyse statique	Aucune	PHPStan Level 10, zéro erreurs
Chiffrement	RC4, AES-128, AES-256	AES-256 uniquement (PDF 2.0 Revision 6)
Signatures	PKCS#7 basique	PAdES B-B à B-LTA
PDF/A	PDF/A-1b (partiel)	PDF/A-4 (ISO 19005-4 complet)
Références croisées	Tables xref legacy	Flux de références croisées
Gestion des polices	Format binaire propriétaire	TTF/OTF standard, subsetting automatique
Analyse HTML	Basée sur regex (limitée)	Moteur basé sur DOM (support CSS amélioré)
Dépendances	Zéro	Zéro

Mapping API : Ancienne méthode vers nouvelle méthode

Le changement le plus visible est la surface de l'API. TCPDF-Next utilise camelCase, paramètres nommés, objets de valeur et constructeurs fluides :

TCPDF Legacy	TCPDF-Next	Notes
new TCPDF()	Document::create()	Constructeur fluide, params nommés
$pdf->Cell()	$pdf->cell()	camelCase
$pdf->MultiCell()	$pdf->multiCell()	camelCase
$pdf->SetFont()	$pdf->setFont()	camelCase
$pdf->SetDrawColor()	$pdf->setDrawColor()	camelCase
$pdf->Output('file.pdf', 'F')	$pdf->save('file.pdf')	Méthode explicite
$pdf->Output('file.pdf', 'I')	$pdf->output('file.pdf', OutputDestination::Inline)	Basé sur enum

Création de document

$pdf = new TCPDF('P', 'mm', 'A4', true, 'UTF-8', false); 
$pdf->SetCreator('My App'); 
$pdf->SetAuthor('John Doe'); 
$pdf->SetTitle('Invoice #12345'); 
$pdf->SetKeywords('invoice, payment, monthly'); 
$pdf->setPrintHeader(false); 
$pdf->setPrintFooter(false); 
$pdf->SetMargins(15, 15, 15); 
$pdf->SetAutoPageBreak(true, 15); 
$pdf->AddPage(); 
use YeeeFang\TcpdfNext\Document\PdfDocument; 
use YeeeFang\TcpdfNext\Document\PageFormat; 
use YeeeFang\TcpdfNext\Document\Orientation; 
use YeeeFang\TcpdfNext\Document\Margins; 
$pdf = PdfDocument::create() 
    ->setCreator('My App') 
    ->setAuthor('John Doe') 
    ->setTitle('Invoice #12345') 
    ->setKeywords(['invoice', 'payment', 'monthly']) 
    ->setPageFormat(PageFormat::A4) 
    ->setOrientation(Orientation::PORTRAIT) 
    ->setMargins(Margins::uniform(15)) 
    ->setAutoPageBreak(true, bottomMargin: 15) 
    ->build(); 
$page = $pdf->addPage(); 

Changements de configuration : Constantes vers Enums

TCPDF legacy utilisait des constantes entières et des chaînes magiques. TCPDF-Next utilise les enums PHP 8.1+ :

// TCPDF : Entiers magiques pour mode de chiffrement
$pdf->SetProtection(['print', 'copy'], 'user', 'owner', 3); 

// TCPDF-Next : Enums type-safe
$pdf->setEncryption() 
    ->setAlgorithm(EncryptionAlgorithm::AES256) 
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY | Permissions::COPY) 
    ->setUserPassword('user') 
    ->setOwnerPassword('owner') 
    ->apply(); 

Gestion des couleurs : Tableaux vers objets de valeur Color

// TCPDF : Tableaux d'entiers bruts
$pdf->SetDrawColor(255, 0, 0); 
$pdf->SetFillColor(0, 128, 255); 

// TCPDF-Next : Objets de valeur Color
use YeeeFang\TcpdfNext\Color\Color; 
$canvas->setStrokeColor(Color::rgb(255, 0, 0)); 
$canvas->setFillColor(Color::rgb(0, 128, 255)); 
$canvas->setFillColor(Color::hex('#0080FF')); 
$canvas->setFillColor(Color::cmyk(100, 50, 0, 0)); 

Taille de page : Chaînes vers objets de valeur PageSize

// TCPDF : Chaînes magiques
$pdf = new TCPDF('P', 'mm', 'A4'); 
$pdf->AddPage('L', 'LETTER'); 

// TCPDF-Next : Enums et objets de valeur type-safe
use YeeeFang\TcpdfNext\Document\PageFormat; 
use YeeeFang\TcpdfNext\Document\Orientation; 
$pdf = PdfDocument::create() 
    ->setPageFormat(PageFormat::A4) 
    ->build(); 
$page = $pdf->addPage(PageFormat::LETTER, Orientation::LANDSCAPE); 
$custom = $pdf->addPage(PageFormat::custom(100, 200)); // mm

Chiffrement : RC4/AES-128 vers AES-256 uniquement

TCPDF-Next supprime tous les algorithmes de chiffrement legacy. Si votre application utilise le chiffrement RC4 ou AES-128, vous devez passer à AES-256 :

// TCPDF : Plusieurs algorithmes (incluant non sécurisés)
$pdf->SetProtection(['print'], 'user', 'owner', 0); // RC4-40 -- NON SÉCURISÉ
$pdf->SetProtection(['print'], 'user', 'owner', 1); // RC4-128 -- NON SÉCURISÉ
$pdf->SetProtection(['print'], 'user', 'owner', 2); // AES-128
$pdf->SetProtection(['print'], 'user', 'owner', 3); // AES-256

// TCPDF-Next : AES-256 uniquement (la seule option sécurisée)
$pdf->setEncryption() 
    ->setAlgorithm(EncryptionAlgorithm::AES256) // Seule option
    ->setUserPassword('user') 
    ->setOwnerPassword('owner') 
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY) 
    ->apply(); 

WARNING

Les PDF chiffrés avec RC4 ou AES-128 par TCPDF legacy devraient être rechiffrés avec AES-256. Le chiffrement RC4 ne fournit aucune sécurité significative — des outils existent pour le casser en secondes.

Liste de contrôle des changements incompatibles

Vérifiez cette liste avant de démarrer votre migration :

• [ ] PHP 8.5+ requis — Mettez à niveau votre runtime PHP. PHP 7.x et 8.0-8.4 ne sont pas supportés.
• [ ] Changement d'espace de noms — Remplacez les références de classe TCPDF par les espaces de noms YeeeFang\TcpdfNext\....
• [ ] Méthodes camelCase — SetFont() devient setFont(), MultiCell() devient multiCell(), etc.
• [ ] Constructeur remplacé — new TCPDF(...) devient PdfDocument::create()->...->build().
• [ ] Méthode Output remplacée — Output('file.pdf', 'F') devient save('file.pdf').
• [ ] Changement de format de police — Remplacez les fichiers de police binaires TCPDF (.php + .z) par les fichiers TTF/OTF originaux.
• [ ] Méthodes Header/Footer — Remplacez l'héritage de classe (extends TCPDF) par des callbacks d'événement (onPageHeader()).
• [ ] Mise à niveau chiffrement — RC4 et AES-128 sont supprimés. Migrez vers AES-256.
• [ ] Tableaux de couleurs — Remplacez les tableaux bruts [255, 0, 0] par Color::rgb(255, 0, 0).
• [ ] Tailles de page chaînes — Remplacez les chaînes 'A4' par les valeurs enum PageFormat::A4.
• [ ] Format de mots-clés — Changez la chaîne séparée par virgules en tableau : 'a, b' devient ['a', 'b'].
• [ ] Paramètre unit supprimé — TCPDF-Next utilise les millimètres par défaut (configurable par document).
• [ ] Types de retour — Beaucoup de méthodes retournent maintenant des résultats typés au lieu de void. Utilisez les valeurs de retour #[\NoDiscard].

Couche de compatibilité (migration graduelle)

Pour les grandes bases de code, TCPDF-Next fournit une couche de compatibilité qui mappe la plupart des appels de méthode legacy :

// Remplacez votre import — le code existant continue de fonctionner
use YeeeFang\TcpdfNext\Compat\TcpdfCompat as TCPDF;

La couche de compatibilité couvre environ 80% de l'API publique de TCPDF. Les méthodes non supportées lancent DeprecatedMethodException avec des conseils sur l'équivalent moderne.

WARNING

La couche de compatibilité est une aide à la migration, pas une solution permanente. Elle ajoute de la surcharge et n'expose pas les fonctionnalités avancées de TCPDF-Next (signatures PAdES, PDF/A-4, flux de références croisées). Prévoyez de compléter votre migration vers l'API native.

Mapping API complet

Pour une référence méthode par méthode complète couvrant plus de 30 méthodes, voir la Table de mapping API.

Lecture complémentaire

• Table de mapping API — Mapping méthode par méthode complet
• Aperçu Sécurité — Corrections de CVE traitées dans la migration
• Référence API — Documentation API complète TCPDF-Next
• FAQ — Questions courantes de migration