Guide développeur pour la compatibilité TCPDF

En bref

L’adaptateur de compatibilité est une couche de migration. Son rôle est de rendre le comportement hérité visible, pas de le masquer. Sers-t’en pour garder une application en service pendant que tu déplaces les chemins à forte valeur vers les API natives de NextPDF.

Utilise ce guide quand tu maintiens du code hérité de style TCPDF, que tu ajoutes de la couverture à l’adaptateur ou que tu planifies une migration progressive vers les API natives de NextPDF.

Frontière d’architecture

Couche	Responsable	Responsabilité	À ne pas placer ici
Application héritée	Application	Garder les appels existants de style TCPDF en service pendant la migration.	Nouvelles fonctionnalités PDF qui doivent utiliser les API natives de NextPDF.
Coquille de l’adaptateur	nextpdf/compat-legacy	Exposer la classe de forme TCPDF et l’état de compatibilité partagé.	Familles de méthodes étendues ou logique de conversion.
Traits de responsabilité	nextpdf/compat-legacy	Regrouper les familles de méthodes héritées : texte, polices, images, sécurité, formulaires, pages.	Politique de sortie entre familles.
Classes de pont	nextpdf/compat-legacy	Convertir les arguments, destinations, couleurs, unités et formats hérités.	Comportement propre au métier.
Moteur principal	nextpdf/nextpdf	Produire le document natif.	Promesses de compatibilité héritée.

Cycle de vie à l’exécution

Étape	Comportement	Action du développeur
Amorçage	L’amorçage hérité facultatif expose les noms de compatibilité.	À utiliser uniquement là où le code hérité attend des symboles TCPDF.
Construction	Les arguments du constructeur hérité sont adaptés à la configuration du document principal.	Garde les entrées du constructeur stables pendant la migration.
Appel de méthode	Les méthodes prises en charge sont mappées au comportement de NextPDF via les responsabilités et les ponts.	Vérifie la couverture des méthodes avant de supposer une parité.
Fonctionnalité non prise en charge	Un comportement non pris en charge lève des exceptions de compatibilité explicites.	Remplace l’appel ou isole-le derrière du code applicatif.
Sortie	Le pont de sortie mappe le comportement de destination hérité vers la sortie de NextPDF.	Valide les noms de fichiers et les racines de stockage.

Inventaire de migration

Commence par recenser chaque appel de méthode TCPDF dans l’application. Classe chaque appel avant d’en modifier le comportement.

Classification	Signification	Action
Méthode d’adaptateur prise en charge	La méthode est documentée comme prise en charge et dispose de tests.	À conserver temporairement, puis à migrer quand tu touches à la zone.
Méthode d’adaptateur partielle	La méthode existe mais son comportement ne correspond pas entièrement au TCPDF hérité.	Ajoute des tests à partir de fixtures et valide la sortie manuellement.
Méthode explicitement non prise en charge	L’adaptateur lève une exception de compatibilité.	Remplace par du natif NextPDF ou supprime la fonctionnalité.
Wrapper propre au métier	L’application encapsule déjà les appels TCPDF.	Migre d’abord l’intérieur du wrapper.
Appel sensible à la conformité	Flux de signature, chiffrement, balisage, PDF/A, accessibilité ou facturation.	Migre vers les API natives de NextPDF avec une vérification dédiée.

Modèle de contribution à l’adaptateur

Ajoute la prise en charge de compatibilité dans la plus petite famille de méthodes qui détient le comportement.

Type de changement	Où l’implémenter	Test requis
Méthode de sortie de texte	Concerns\AdaptsTextOutput ou responsabilité liée aux polices.	Fixture héritée et assertion sur la sortie native.
Méthode de page ou de marge	Responsabilité liée aux pages, au positionnement ou aux marges.	Test de conversion de coordonnées et d’état de page.
Méthode d’image ou de dessin	Responsabilité liée aux images, au dessin, aux couleurs ou aux dégradés.	Validation des entrées et test de sortie visuelle/structurelle.
Destination de sortie	OutputBridge.	Test du mappage des destinations et des chemins non sûrs.
Fonctionnalité non prise en charge	Fabrique d’exceptions ou table de couverture des méthodes.	Test du type d’exception et du message.

N’ajoute pas une méthode importante directement à la coquille de l’adaptateur quand un trait de responsabilité détient la famille.

Modèle de migration native

Sers-toi de l’adaptateur pour stabiliser, puis déplace les flux de travail stables vers les API natives.

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

Traite la migration comme une suite de petits déplacements de comportement. Une page peut continuer à utiliser l’adaptateur pendant que tu fais passer une section à haut risque aux API natives.

Points d’extension

Point d’extension	À utiliser pour	Contrainte
AdaptationConfig	Contrôler le comportement de l’adaptateur pendant la migration.	Garde les valeurs par défaut explicites et revues.
Traits de responsabilité	Regrouper des familles de méthodes comme le texte, les formulaires, les images ou la sécurité.	Ajoute les méthodes à la responsabilité appropriée, pas à la coquille de l’adaptateur.
Classes de pont	Convertir les formes d’arguments héritées en valeurs principales.	Maintiens le comportement des ponts couvert par des tests de migration.
CompatAdapterInterface	Abstraction de l’adaptateur pour l’outillage.	Ne l’utilise pas en remplacement des contrats principaux natifs dans du nouveau code.
Table de couverture des méthodes	Registre de prise en charge destiné aux développeurs.	À mettre à jour quand l’état de prise en charge change.

Flux de travail de migration

1. Installe l’adaptateur et exécute la suite de tests héritée sans la modifier.
2. Ouvre la couverture des méthodes et classe chaque méthode appelée.
3. Remplace d’abord les méthodes non prises en charge.
4. Déplace les chemins à fort volume ou sensibles à la conformité vers les API principales natives.
5. Ajoute une couverture par fixtures pour chaque famille de méthodes migrée.
6. Supprime les alias d’amorçage une fois qu’aucun point d’entrée applicatif n’en dépend.

Gestion des échecs

Échec	Où il doit être géré	Réponse recommandée
Méthode non prise en charge	Exception de l’adaptateur.	Remplace l’appel ou isole-le derrière un adaptateur applicatif.
Parité partielle de mise en page	Tests de migration et revue visuelle.	Documente la différence acceptée avant le déploiement.
Destination de sortie non sûre	OutputBridge et politique de stockage de l’application.	Rejette les chemins non sûrs et privilégie les API de sortie natives.
Incompatibilité de fonctionnalité de sécurité	Plan de migration native.	Ne livre pas uniquement le comportement de compatibilité pour des sorties réglementées.
Collision d’alias d’amorçage	Amorçage de l’application.	Supprime les alias globaux ou limite-les aux points d’entrée hérités.

Valeurs par défaut sûres

Responsabilité	Valeur par défaut	Quand la remplacer
Méthodes non prises en charge	Lever une exception explicite.	Ne l’assouplis pas en production.
Valeurs par défaut héritées	Centralisées dans LegacyDefaults.	À ne remplacer que pour un comportement de migration connu.
Mappage de sortie	Passe par OutputBridge.	Utilise les API de sortie natives après la migration.
Source de couverture	Page de couverture des méthodes et tests.	Relance les contrôles de couverture après chaque mise à niveau de l’adaptateur.
Mode strict	Garde-le activé pendant les audits de migration.	À désactiver uniquement pour une fenêtre de compatibilité héritée documentée.

Liste de vérification des tests

• Conserve une fixture héritée pour chaque famille de méthodes migrée.
• Ajoute un test natif NextPDF avant de remplacer une méthode héritée.
• Vérifie que les méthodes non prises en charge lèvent l’exception documentée.
• Compare la structure de sortie lorsque l’égalité exacte des octets n’est pas un objectif de migration réaliste.
• Exécute les contrôles de couverture des méthodes après avoir ajouté ou modifié des méthodes d’adaptateur.
• Ajoute des tests de chemin de stockage pour chaque destination de sortie utilisée par le code hérité.