Migrer hors du legacy : TCPDF, FPDF et consorts

SpecSpec: ISO 32000-2ISO 32000-2SpecSpec: ISO 19005-4ISO 19005-4SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1

En bref

Si tes PDF sont générés par TCPDF, FPDF, mPDF ou dompdf, le code fonctionne probablement toujours. C’est précisément pour cela que le problème passe facilement inaperçu. La bibliothèque tourne, le fichier s’ouvre, et l’écart n’apparaît que le jour où quelqu’un réclame un document signé, archivable ou accessible, et que la réponse est « nous ne pouvons pas le faire d’ici ».

Cette page raconte l’histoire de la migration : ce que sont ces murs, pourquoi ils sont structurels plutôt qu’accidentels, et comment NextPDF t’offre un chemin de sortie progressif — y compris une surface de compatibilité TCPDF qui est une aide à la migration, et non la promesse d’un remplacement transparent et identique à l’octet près.

Pourquoi c’est important

Une bibliothèque de PDF n’est pas un appel de rendu que tu effectues une seule fois. C’est une dépendance dont tes documents héritent tant qu’ils existent. Lorsque cette dépendance cesse d’avancer, tes documents cessent de pouvoir faire des choses nouvelles — et tu t’en rends compte au pire moment possible, quand un client, un auditeur ou un régulateur place la barre.

Les murs ressemblent à ceci. Le format a évolué : PDF 2.0 est l’édition actuelle de la norme (SpecSpec: ISO 32000-2ISO 32000-2), et un générateur resté sur la structure 1.x est en retard sur le format que le reste de ta chaîne d’outils suppose désormais. La signature est mince ou rapportée après coup, bien en deçà des profils de référence PAdES qui font tenir une signature (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4). La sortie d’archivage vers la famille PDF/A, et la structure balisée pour l’accessibilité, sont soit absentes, soit fragiles. Et l’API elle-même n’est pas typée — orientations en chaîne de caractères, booléens positionnels, valeurs par défaut que tu découvres par accident — si bien que le compilateur ne peut pas t’aider, et un relecteur non plus.

Aucun de ces problèmes n’est un bug que tu peux contourner par un correctif. Ils sont la forme d’un outil conçu pour une décennie antérieure, et plusieurs de ces outils n’avancent plus activement vers les normes que tes documents doivent désormais respecter.

La version courte

• Les bibliothèques PHP de PDF du legacy tournent pour la plupart toujours. Le problème, c’est ce qu’elles ne peuvent généralement pas produire en pleine conformité moderne : PDF 2.0, signatures conformes à la référence, PDF/A validé, accessibilité balisée — le support à travers les bibliothèques citées est limité ou absent.
• NextPDF est un moteur PHP 8.4 qui écrit du PDF 2.0 par défaut, avec des types stricts, des profils d’archivage et la signature PAdES comme sorties de premier ordre.
• Tu n’as pas à tout réécrire dès le premier jour. La surface de compatibilité TCPDF permet aux appels familiers de continuer à fonctionner pendant que tu déplaces la logique documentaire qui compte.
• Cette surface est compatible avec TCPDF, mais non identique à l’octet près. C’est un pont qui te porte à travers la migration, avec des différences de comportement documentées — non l’affirmation que chaque script tourne sans modification.
• Le test honnête, c’est de savoir si les nouvelles capacités valent le déplacement. Pour certaines charges de travail, ce n’est pas le cas, et nous le disons clairement.

L’approche de NextPDF

L’approche consiste à faire de la migration une séquence, et non un saut. Tu continues à produire des documents tout au long du chemin, et tu échanges les anciennes contraintes une à une plutôt que de jouer une livraison entière sur une réécriture en bloc.

1. InventoryCatalogue what your documents actually need to emit — signatures, archival profiles, tagged structure, fonts — not just which calls you make today.
2. BridgeAdopt the TCPDF-compatibility surface so the existing call sites keep producing files while the engine underneath becomes NextPDF.
3. PortMove the document logic that matters onto the native typed API, where intent is explicit and the compiler checks it.
4. UpgradeTurn on the outputs many legacy libraries cannot reach with full modern conformance: PDF 2.0 structure, validated PDF/A, PAdES signatures, tagged accessibility.
5. VerifyConfirm the result against a real validator, so 'archival' or 'signed' means a tool agrees, not just that the file opened.

A staged migration off a legacy PDF library: start on the compatibility surface so existing calls keep working, then move document logic onto the typed native API, then turn on the standards-grade outputs (PDF 2.0, PDF/A, PAdES, accessibility) that many legacy libraries cannot produce with full modern conformance.

PDF 2.0 est la base, pas un drapeau de fonctionnalité. NextPDF écrit l’édition actuelle du format par défaut (SpecSpec: ISO 32000-2ISO 32000-2), et peut sérialiser des structures plus anciennes lorsqu’un profil les demande. Une bibliothèque figée sur la structure 1.x ne peut pas te rejoindre ici ; ce n’est pas un réglage qu’il lui manque, c’est une époque qui la précède.

L’archivage et l’accessibilité sont des propriétés du générateur. Produire un fichier qu’un validateur accepte comme PDF/A est quelque chose que le moteur doit faire au moment où il écrit — cela ne peut pas être agrafé après coup (SpecSpec: ISO 19005-4ISO 19005-4). Il en va de même pour la structure balisée qui rend un PDF accessible. NextPDF les construit pendant la génération, ce qui est précisément l’étape que beaucoup d’outils du legacy ne peuvent pas franchir — ou ne franchissent que partiellement, en deçà de ce qu’un validateur accepte.

La signature franchit la barre de référence. Les signatures électroniques avancées dans un PDF suivent les profils PAdES (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4), où le condensé couvre une plage d’octets déclarée et où la signature porte les métadonnées qu’un validateur contrôle. Un assistant de signature rapporté après coup atteint rarement cette barre. NextPDF la traite comme une sortie de premier ordre, et non comme un détail de dernière minute.

La surface de compatibilité est le pont, énoncé honnêtement. La couche de compatibilité TCPDF existe pour que tes sites d’appel existants continuent à produire des documents pendant que tu migres les parties qui comptent. Elle suit le même modèle que chaque guide de migration NextPDF : compatible avec la bibliothèque source, non identique à l’octet près, avec les différences de comportement consignées. Cette honnêteté est l’essentiel — une affirmation silencieuse de « remplacement transparent à 99 % » est exactement le genre de supposition que ce moteur est conçu pour refuser.

Human-factors note:Human-factors note

La raison de migrer n’est que rarement le code que tu as aujourd’hui ; c’est le document que l’on te demandera demain. La maintenabilité est une propriété de qualité nommée — la facilité avec laquelle un système peut être analysé et modifié à mesure que les besoins évoluent (SpecSpec: ISO/IEC 25010, §3.6ISO/IEC 25010 §3.6). Une dépendance qui a cessé d’avancer l’érode silencieusement, et tu n’en ressens le coût que lorsqu’une nouvelle exigence arrive et que la réponse doit être « pas d’ici ». Un déplacement progressif paie ce coût à ton rythme, pendant que les documents continuent de couler, au lieu de tout payer d’un coup sous la contrainte d’une échéance.

Exemple pratique

La forme d’une migration est modeste au site d’appel. L’ancien code continue de produire un fichier via la surface de compatibilité ; le nouveau code énonce l’intention à travers l’API native typée et réclame une sortie que la bibliothèque du legacy ne peut pas atteindre, ou n’atteint qu’avec une conformité limitée.

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use NextPDF\Contracts\Orientation;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

// 1) The bridge: a familiar TCPDF-shaped call keeps producing a file
//    while the engine underneath is already NextPDF. Behaviour is
//    compatible, not byte-identical — differences are documented.
$legacy = new TCPDF();
$legacy->AddPage();
$legacy->SetFont('helvetica', 'B', 16);
$legacy->Cell(0, 12, 'Migrated invoice', ln: 1);
$bridgedBytes = $legacy->Output('', 'S');

// 2) The destination: the same document expressed natively, where intent
//    is typed and the engine can emit what many legacy tools cannot.
$document = Document::createStandalone();
$document->setTitle('Migrated invoice');
$document->addPage(PageSize::a4(), Orientation::Portrait);
$document->setFont('helvetica', 'B', 16);
$document->cell(0, 12, 'Migrated invoice', newLine: true);

// Bytes only, no HTTP headers, no file side effect — stated, not inferred.
$nativeBytes = $document->output(dest: OutputDestination::String);

Le premier bloc est le point d’appui : rien dans ton application n’a à changer pour que les documents continuent de couler. Le second est la destination : un appel typé où « portrait », « sortie en chaîne » et la police sont explicites, et où l’archivage, la signature et l’accessibilité deviennent des sorties que tu peux activer plutôt que des murs contre lesquels tu butes.

Idée fausse courante

L’espoir fréquent est « il doit bien y avoir un drapeau qui fait faire à mon ancienne bibliothèque du PDF 2.0 et des signatures ». Il n’y en a pas. Ce ne sont pas des options qu’une bibliothèque mature a oublié d’exposer ; ce sont des capacités autour desquelles son architecture n’a jamais été conçue. Tu ne peux pas atteindre par configuration une édition de format ou un profil de signature qu’un générateur n’implémente pas.

L’idée fausse symétrique est que NextPDF est un remplacement transparent à 100 % de TCPDF, si bien que la migration serait gratuite. Elle ne l’est pas, et nous ne prétendrons pas le contraire. La surface de compatibilité couvre une tranche réelle et documentée de l’API pour te porter à travers le déplacement ; certains appels se comportent différemment, et quelques-uns sont hors périmètre. Traite-la comme un pont muni d’une carte publiée, et non comme une garantie que chaque script du legacy tourne sans y toucher.

Limites et périmètre

TCPDF-compatibility surface as a migration aid — edition availability

Edition	Availability
Core	○ La surface de compatibilité est compatible avec TCPDF, mais non identique à l’octet près. Elle couvre un sous-ensemble documenté de l’API pour que les sites d’appel existants continuent de produire des fichiers pendant la migration. C’est un pont, non un remplacement transparent : certains comportements diffèrent et certains appels ne sont pas pris en charge, tous listés dans les pages de couverture des méthodes et de migration. La destination est l’API native typée, où réside la sortie aux normes.
Pro	●Available
Enterprise	●Available

La migration est un moyen, pas une vertu. Si tes documents sont simples, que ta bibliothèque est encore maintenue, et que tu n’auras jamais besoin de PDF 2.0, de signature, de PDF/A ou d’accessibilité, la réponse honnête peut être de rester où tu es — le coût de bascule est réel, et un déplacement dont tu n’as pas besoin est un déplacement que tu ne devrais pas faire. La page sur les cas où ne pas utiliser NextPDF trace cette ligne sans sourciller.

Cette page décrit le chemin de migration et les cibles du moteur. La couverture exacte de l’API, les différences de comportement et la procédure pas à pas vivent dans la documentation de compatibilité, qui fait autorité sur ce que fait chaque appel. Rien ici ne promet qu’un script du legacy arbitraire tourne sans modification.

Documents associés

• Ce qui a changé avec PDF 2.0 — l’édition de format que beaucoup de bibliothèques du legacy ne peuvent pas émettre, et pourquoi cela compte.
• La surface de compatibilité TCPDF — le guide qui fait autorité sur ce que couvre le pont et là où il diffère.
• Cas où ne pas utiliser NextPDF — la frontière honnête, pour qu’une migration dont tu n’as pas besoin soit une migration que tu peux éviter.
• Un seul moteur, tous les frameworks — là où le moteur vers lequel tu migres s’insère dans la pile que tu exploites déjà.

Glossaire

• PDF 2.0 — l’édition actuelle de la norme Portable Document Format (ISO 32000-2). Développé à la première occurrence ; le format que NextPDF écrit par défaut.
• PDF/A — la famille de conformité d’archivage (la série ISO 19005) qui définit ce qui rend un PDF sûr à préserver sur le long terme. Une propriété que le générateur doit produire, et non que l’appelant peut ajouter plus tard.
• PAdES — PDF Advanced Electronic Signatures, la famille de profils ETSI (EN 319 142) pour intégrer des signatures aux normes dans un PDF. Développé à la première occurrence ; couvert en profondeur dans les pages sur la signature.
• Surface de compatibilité — une couche d’API façonnée comme une bibliothèque source (ici, TCPDF) qui permet aux sites d’appel existants de continuer à fonctionner pendant la migration. Compatible avec l’original, mais non identique à l’octet près — un pont, non un remplacement transparent.
• Remplacement transparent (drop-in) — un substitut qui exécute le code existant sans modification. La surface de compatibilité TCPDF est délibérément non décrite ainsi ; c’est une aide à la migration documentée, assortie de différences de comportement connues.