Couverture des méthodes TCPDF dans NextPDF compat-legacy

En bref

nextpdf/compat-legacy est une couche de compatibilité, pas un fork de TCPDF ni un clone comportemental garanti. Elle expose les noms de méthodes publiques, l’ordre des paramètres et les valeurs par défaut de TCPDF 6.x au-dessus du moteur principal NextPDF. La plupart des appels correspondent directement à une opération NextPDF Document. Une minorité clairement délimitée accepte des paramètres hérités que NextPDF ne respecte pas, ou n’a tout simplement aucun effet.

Cette page propose une synthèse lisible de l’audit méthode par méthode. La matrice de couverture faisant autorité, vérifiée par les tests, se trouve dans le dépôt à l’emplacement docs/TCPDF_COVERAGE.md. En cas d’écart entre cette page et la matrice du dépôt, c’est la matrice du dépôt qui l’emporte, car elle est garantie par la suite de tests.

Sers-toi de cette page pour répondre à une question avant de migrer : pour chaque méthode TCPDF que ta base de code appelle, que fait réellement l’adaptateur ?

Résumé de la couverture

L’audit a passé en revue environ 120 méthodes publiques de TCPDF 6.x. Chacune a été classée dans exactement l’une des quatre catégories.

Catégorie	Nombre	Ce que cela signifie pour toi
Reflétées — délégation complète	94	L’appel correspond directement à une méthode NextPDF `Document`. Le comportement est compatible pour les paramètres documentés.
Ignorées en silence — partielles	15	La méthode s’exécute et produit une sortie, mais un ou plusieurs paramètres TCPDF n’ont aucun effet. La différence de comportement est documentée.
Non implémentées — corps sans effet	4	La méthode existe pour la compatibilité du code source, mais ne fait rien.
Sans objet	7	La méthode TCPDF n’a aucun effet sur la sortie PDF ; elle est intentionnellement exclue.
Méthodes de dérive de l’API moderne ajoutées	17	Méthodes Document de NextPDF v5.1+ exposées sur l’adaptateur pour que le code mêlant les deux API compile. Aucun équivalent TCPDF 6.x.

Ces chiffres proviennent de docs/TCPDF_COVERAGE.md §Summary. La matrice est vérifiée par tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php et tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php.

Note de formulation. Ce paquet ne prétend pas être un « remplacement direct » ni « 100 % compatible TCPDF ». Il couvre 94 des quelque ~120 méthodes TCPDF passées en revue par délégation directe ; les méthodes restantes portent des différences de comportement documentées, décrites ci-dessous. La description exacte est alternative compatible TCPDF avec une surface de compatibilité connue et testée.

Une remarque sur le décompte des méthodes

L’adaptateur est construit à partir de 25 traits à responsabilité unique (src/Compat/Tcpdf/Concerns/) exposant 273 méthodes publiques au total, plus un petit nombre de méthodes de cycle de vie et d’échappatoire sur la classe TCPDF elle-même. Les catégories de couverture ci-dessus comptent les méthodes distinctes de la surface d’API TCPDF 6.x (~120), pas le nombre total de méthodes publiques de l’adaptateur. Les deux nombres mesurent des choses différentes : la couverture de la surface d’API par rapport à la taille de l’implémentation. Si tu vois dans le README.md du paquet un nombre de traits ou de méthodes plus petit, considère docs/TCPDF_COVERAGE.md et cette page comme faisant autorité — le résumé du README est antérieur au trait AdaptsDriftV51.

1. Méthodes reflétées — délégation compatible

Quatre-vingt-quatorze méthodes correspondent directement à l’instance NextPDF\Core\Document sous-jacente. Les noms TCPDF en PascalCase correspondent aux noms NextPDF en camelCase lorsque le moteur utilise le camelCase ; l’adaptateur accepte les deux graphies pour la compatibilité ascendante et descendante.

Groupes représentatifs (table complète : docs/TCPDF_COVERAGE.md §1) :

Domaine TCPDF	Exemples de méthodes	Trait de l’adaptateur
Cycle de vie	`Output()`, `Close()`, `getPDFData()`	`AdaptsLifecycle`
Pages	`AddPage()`, `getNumPages()`, `deletePage()`	`AdaptsPageManagement`
Texte	`Cell()`, `MultiCell()`, `Write()`, `Text()`, `Ln()`	`AdaptsTextOutput`
Polices	`SetFont()`, `SetFontSize()`, `AddFont()`	`AdaptsFonts`
Couleurs	`SetTextColor()`, `SetDrawColor()`, `SetFillColor()`	`AdaptsColors`
Dessin	`Line()`, `Rect()`, `Circle()`, `Polygon()`, `Arrow()`	`AdaptsDrawing`
Transformations	`Rotate()`, `Scale()`, `Translate()`, `Skew()`, `Mirror*()`	`AdaptsTransforms`
Navigation	`AddLink()`, `Annotation()`, `addTOC()`	`AdaptsNavigation`

Pour ces méthodes, le comportement observé est compatible avec TCPDF 6.x pour les paramètres documentés par NextPDF. L’adaptateur ne garantit pas une sortie PDF identique au bit près. Le moteur sous-jacent est une implémentation PDF 2.0 indépendante : les octets rendus diffèrent donc, même lorsque le résultat visible est équivalent. Si tes tests vérifient les octets PDF exacts plutôt que le contenu rendu, attends-toi à devoir réétalonner ces assertions. Consulte /integrations/tcpdf-compat/migration/ pour la stratégie de réétalonnage recommandée.

2. Méthodes ignorées en silence — différences de comportement documentées

Ces 15 méthodes s’exécutent et produisent une sortie, mais au moins un paramètre TCPDF est accepté pour la compatibilité du code source, puis ignoré. C’est la section la plus importante à lire avant de migrer, car l’appel n’échoue pas — il en fait silencieusement moins que l’appel TCPDF d’origine.

Méthode TCPDF	Paramètres ignorés	Alternative compatible
`Image()`	type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs	NextPDF `image()` prend file, x, y, width, height. Pour une image cliquable, dessine l’image, puis ajoute `Document::link()` par-dessus le même rectangle. Le masquage d’image et les images de remplacement ne sont pas pris en charge.
`writeHTML()`	ln, fill, reseth, cell, align	NextPDF `writeHtml()` ne gère que le contenu. Place le HTML dans un bloc positionné via l’API moderne pour contrôler la mise en page.
`writeHTMLCell()`	border (forme chaîne), ln, fill, reseth, autopadding	La largeur, la hauteur, la position et une bordure booléenne sont respectées ; une mise en page de cellule plus riche n’a pas de correspondance.
`ImageEps()`	link, useBoundingBox, align, palign, border, fitonpage, fixoutvals	Position et taille uniquement.
`ImageSVG()`	link, align, palign, border, fitonpage	Position et taille uniquement.
`SetProtection()`	mode (non nul), pubkeys (non vide)	NextPDF utilise toujours AES-256 pour le gestionnaire standard. Pour un chiffrement basé sur certificat, utilise la méthode moderne `setPublicKeyEncryption()` exposée sur l’adaptateur (voir /integrations/tcpdf-compat/security-and-operations/).
`Bookmark()`	style, color, x, isNamedDest	Le titre, le niveau et la position y sont respectés.
`setDestination()`	page, x	Le nom et la position y sont respectés.
`Link()`	spaces	Suivi des espaces interne à TCPDF ; aucun équivalent dans le moteur.
`Annotation()`	clés d’option au-delà de Subtype, spaces	Le type, la position et le texte sont respectés.
`SetLineStyle()`	détail du motif de tirets au-delà de la largeur	Les principales propriétés de ligne sont mappées.
`setAlpha()`	mappage partiel des modes de fusion	Certains noms de modes de fusion n’ont pas d’équivalent dans le moteur.
`Polycurve()`	liste complète des paramètres	Sans effet en mode par défaut ; aucun équivalent dans le moteur.
`PieSectorXY()`	liste complète des paramètres	Mappage partiel (les lignes du centre vers le bord diffèrent).
`RoundedRectXY()`	rayon par coin	Rayon de coin uniforme uniquement.

La manière dont l’adaptateur signale ces différences dépend du mode strict (voir /integrations/tcpdf-compat/configuration/). Avec le mode strict désactivé (la valeur par défaut rétrocompatible), ces appels se dégradent silencieusement. Avec le mode strict activé, chaque appel qui ignore un paramètre lève TcpdfNotImplementedException avec la liste exacte des paramètres ignorés et un indice de migration. Le mode strict est un outil d’audit, pas un réglage de production.

La conception du mode strict suit le principe selon lequel un appelant doit pouvoir constater quand son intention n’a pas été respectée. OWASP ASVS 5.0 §16.5.3 indique qu’une application doit échouer de manière contrôlée et sûre, et empêcher les conditions de défaillance permissive. La perte silencieuse de paramètres est un piège d’expérience développeur plutôt qu’une vulnérabilité, mais le même principe de défaillance explicite s’applique. Le condensé de clause épinglé se trouve dans le champ d’en-tête citations de la page.

3. Méthodes non implémentées — corps sans effet

Quatre méthodes existent pour que le code source hérité compile, mais leur corps ne fait rien. Avec le mode strict activé, trois d’entre elles lèvent TcpdfNotImplementedException. La quatrième (Open()) est une absence d’effet sûre et délibérée qui ne lève jamais d’exception, car la supprimer du code hérité est toujours sans danger.

Méthode TCPDF	Comportement	Remplacement
`setSignature()`	Sans effet (ne stocke rien d’exploitable). Lève une exception en mode strict.	La signature numérique requiert une édition commerciale de NextPDF. Utilise l’API de signature moderne avec un objet-valeur `CertificateInfo` — voir /integrations/tcpdf-compat/security-and-operations/.
`addEmptySignatureAppearance()`	Sans effet. Lève une exception en mode strict.	Même restriction d’édition commerciale que `setSignature()`.
`endPage()`	Sans effet. Lève une exception en mode strict.	NextPDF gère automatiquement le cycle de vie des pages. Retire l’appel.
`Open()`	Absence d’effet sûre. Ne lève jamais d’exception.	NextPDF ouvre automatiquement le document. Retirer l’appel est toujours sans danger.

La signature n’est pas disponible dans le moteur principal via cet adaptateur. L’adaptateur expose un point d’entrée de signature moderne qui délègue au moteur ; la prise en charge de la signature de base est réservée à une édition commerciale. Cette documentation ne prétend rien quant aux profils de signature à validation à long terme ou horodatés, quelle que soit l’édition — voir /integrations/tcpdf-compat/security-and-operations/ pour l’énoncé exact et prudent.

4. Méthodes sans objet

Sept méthodes TCPDF n’ont aucun effet sur la sortie PDF et sont intentionnellement exclues. Les appeler n’a pas de conséquence.

Méthode TCPDF	Raison de l’exclusion
`setDocCreationTimestamp()` / `setDocModificationTimestamp()`	L’état est conservé sur l’adaptateur, mais n’est pas relié aux métadonnées XMP du document. Il n’est pas visible dans la sortie.
`setSRGBmode()`	La gestion des couleurs de NextPDF est indépendante de cet indicateur.
`setPDFVersion()`	NextPDF sélectionne la version du PDF à partir de son profil conformance/output ; il n’y a pas de mutateur direct. L’adaptateur émet un avis et continue.
`setDocInfoUnicode()`	NextPDF est toujours en Unicode ; l’indicateur est sans effet par conception.
`setDefaultMonospacedFont()`	Aucun équivalent dans le moteur ; le style HTML/CSS s’applique à la place.
`setFontSubsetting()`	NextPDF crée toujours des sous-ensembles des polices intégrées ; l’indicateur est en pratique toujours actif.

La version du PDF est fixée par le moteur. La sortie est écrite en PDF 2.0 (ISO 32000-2). ISO 32000-2 §7.5.2 précise qu’un générateur conforme identifie la version du document — dans l’en-tête du fichier ou dans l’entrée Version du catalogue — comme étant 2.0. Elle précise également que la version d’un fichier n’est pas abaissée vers une version plus ancienne lors de l’enregistrement. C’est cohérent avec le comportement de l’adaptateur : des appels tels que setPDFVersion('1.4') ne peuvent pas cibler une version de PDF plus ancienne via cet adaptateur. Le condensé de clause épinglé se trouve dans le champ d’en-tête citations de la page.

5. Méthodes de dérive de l’API moderne

Dix-sept méthodes du moteur principal NextPDF v5.1+ sont exposées sur l’adaptateur (trait AdaptsDriftV51) afin que le code qui mêle l’API TCPDF à l’API moderne compile toujours. Elles n’ont aucun équivalent TCPDF 6.x. Exemples : getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). Traite-les comme relevant de l’API moderne, et non comme une partie du contrat de compatibilité TCPDF.

6. Conseils de dépréciation et de remplacement

Si ton code appelle…	Statut	Fais plutôt ceci
`Error()`	Comportement modifié (durci)	Le `die()` de TCPDF est remplacé par la levée d’une `RuntimeException`. Entoure les appels risqués d’un `try`/`catch` ; ne compte pas sur l’arrêt du processus.
`setPDFVersion()`	Sans objet	Retire-le. La sortie est toujours en PDF 2.0.
`setUserRights()`	Déprécié en PDF 2.0	Retire-le. L’appel émet un avis `E_USER_DEPRECATED` et est ignoré.
`setSignature()`	Non implémenté dans le moteur principal	Migre vers l’API de signature moderne sur une édition commerciale.
`Image(...)` avec des paramètres supplémentaires	Ignoré en silence	Réduis à file, x, y, w, h ; ajoute `Document::link()` pour les images cliquables.
`endPage()` / `Open()`	Non implémenté / sans effet	Retire-les.

7. Étapes de migration sûre

Installe le paquet et exécute ta suite existante contre l’adaptateur sans modifier le code — voir /integrations/tcpdf-compat/install/ et /integrations/tcpdf-compat/quickstart/.
Active le mode strict lors d’une exécution d’audit dédiée (pas en production) : $pdf->setStrictMode(true);. Recueille chaque TcpdfNotImplementedException. Chacune nomme les paramètres exacts ignorés et un indice de migration.
Pour chaque site de levée d’exception, choisis : abandonner le paramètre ignoré, ou migrer cet appel vers l’API moderne via $pdf->getDocument().
Réétalonne tout test qui vérifie les octets PDF exacts ; vérifie plutôt le contenu rendu ou des propriétés structurelles.
Désactive le mode strict et déploie le chemin de code audité. Conserve une tâche CI périodique en mode strict pour détecter les régressions au fil de tes refactorisations.

Procédure complète avec code : /integrations/tcpdf-compat/migration/.

Voir aussi

docs/TCPDF_COVERAGE.md — matrice de couverture faisant autorité, vérifiée par les tests (dans le dépôt)
/integrations/tcpdf-compat/migration/ — stratégie de migration de bout en bout de TCPDF vers NextPDF
/integrations/tcpdf-compat/configuration/ — mode strict et configuration de l’adaptateur
/integrations/tcpdf-compat/security-and-operations/ — posture de chiffrement et de signature
/integrations/tcpdf-compat/integration/ — intégration de l’adaptateur dans une application
/integrations/tcpdf-compat/boot-and-discovery/ — enregistrement des alias de classe et exposition de la façade