Référence de l'API de compatibilité TCPDF

En bref

Le package nextpdf/compat-legacy expose une classe principale, NextPDF\Compat\Tcpdf\TCPDF, qui reproduit l’API publique de TCPDF 6.x tout en confiant le rendu au moteur moderne NextPDF. Il expose aussi un petit ensemble de composants complémentaires : un LegacyBootstrap pour les alias de classe globaux, une surface de configuration AdaptationConfig/LegacyDefaults, des classes internes de pont (sortie, constructeur, couleur, unité, format de page) et des exceptions de compatibilité. C’est un outil de migration, pas une dépendance permanente. Le statut complet des méthodes héritées est détaillé dans le tableau de couverture des méthodes. Cette page documente les surfaces sur lesquelles le code applicatif devrait s’appuyer intentionnellement.

Commence par ici : si tu débutes avec ce package, instancie NextPDF\Compat\Tcpdf\TCPDF, effectue tes appels TCPDF habituels (AddPage(), SetFont(), Cell()) et termine par Output($name, $dest). À elle seule, cette classe est le point d’entrée de presque tout ce qui suit. Consulte Tâches courantes pour des points de départ exécutables.

Tâches courantes

Ce sont les cas d’usage concrets les plus fréquents avec ce package. Chaque bloc a été vérifié avec le code source de l’adaptateur et est exécutable tel quel.

Produis un PDF avec les appels TCPDF familiers et récupère-le sous forme de chaîne (pour une file d’attente, une réponse HTTP ou du stockage) :

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetTitle('Invoice 1234');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$bytes = $pdf->Output('invoice.pdf', 'S');

Ce que ça fait : construit un document PDF 2.0 via l’adaptateur compatible avec l’API TCPDF et renvoie les octets bruts (%PDF...) parce que la destination 'S' passe par OutputBridge vers Document::getPdfData() au lieu d’utiliser echo, ce qui est sûr dans un worker ou un contrôleur.

Exécute le code new \TCPDF(...) existant sans modifier le code source en enregistrant une seule fois les alias globaux au démarrage :

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/legacy.pdf', 'F');

Ce que ça fait : enableAliases() enregistre de façon idempotente \TCPDF (ainsi que les aides \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES) uniquement quand ces noms ne sont pas déjà définis, afin que le code hérité inchangé s’exécute sur l’adaptateur.

Audite une migration en faisant remonter chaque paramètre TCPDF qui serait sinon ignoré silencieusement :

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter
}

Ce que ça fait : avec setStrictMode(true), un appel qui ne peut pas reproduire le comportement de TCPDF lève TcpdfNotImplementedException en indiquant les paramètres ignorés. Cela transforme une dégradation silencieuse en une liste de tâches de migration (à n’exécuter que pendant une passe d’audit, jamais en production).

Adaptateur principal

Ce tableau décrit la surface canonique de l’adaptateur. Consulte-le quand tu as besoin de la classe à instancier (TCPDF), de ses méthodes de mode strict et de ses échappatoires, ainsi que du contrat qu’elle implémente.

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
`NextPDF\Compat\Tcpdf\TCPDF`	Les paramètres du constructeur reprennent la signature TCPDF héritée via `ConstructorBridge`.	Crée un adaptateur adossé à un document NextPDF.	`TCPDF`	Exceptions de validation du constructeur ou de fonctionnalité non prise en charge.	À utiliser pendant la migration, pas dans du nouveau code NextPDF natif.
`TCPDF::getDocument()`	aucun.	Renvoie le document NextPDF sous-jacent.	`NextPDF\Core\Document`	aucun attendu.	Échappatoire pour le code de migration qui doit combiner des appels hérités et natifs.
`TCPDF::getUnitConverter()`	aucun.	Renvoie le convertisseur créé à partir de l’unité héritée.	`UnitConverter`	aucun attendu.	À utiliser pour les diagnostics de migration, pas pour du code applicatif ordinaire.
`TCPDF::setStrictMode(bool $enabled)`	Indicateur de mode strict.	Active ou désactive l’échec explicite pour le comportement de compatibilité non pris en charge.	`static`	aucun attendu.	Garde-le activé pendant les audits de migration.
`TCPDF::isStrictMode()`	aucun.	Renvoie l’indicateur de mode strict actuel.	`bool`	aucun attendu.	Utile dans les assertions de test.
`TCPDF` méthodes héritées	Varie selon la méthode.	Les méthodes prises en charge correspondent à des appels du document du core ; les méthodes non prises en charge échouent explicitement.	Varie selon la méthode.	`TcpdfNotImplementedException` ou `UnsupportedFeatureException`.	Vérifie la couverture des méthodes avant de t’appuyer sur une méthode.
`CompatAdapterInterface::getDocument()`	aucun.	Méthode du contrat implémentée par `TCPDF`.	`Document`	aucun attendu.	Permet à l’outillage d’atteindre le document natif.
`CompatAdapterInterface::Output(string $name = '', string $dest = '')`	Nom de fichier et destination héritée.	Délègue au pont de sortie.	`string`	Erreurs d’écriture du core ou de destination non prise en charge.	Reproduit le point d’entrée hérité de TCPDF pour la sortie ; l’implémentation concrète de `TCPDF::Output` fournit les valeurs par défaut `'doc.pdf'`/`'I'`.

Groupes de méthodes héritées

Ce tableau cartographie les familles de méthodes TCPDF que l’adaptateur couvre. Parcours-le pour repérer, à grands traits, où aboutit un appel hérité donné avant de vérifier son statut exact dans la couverture des méthodes.

Groupe	Symboles représentatifs	Comportement par défaut	Notes
Cycle de vie et sortie	`Open()`, `Close()`, `Output()`, `getPDFData()`	Maintient un cycle de vie de document à la manière de TCPDF au-dessus d’un document natif.	Privilégie les API natives de sortie après la migration.
Métadonnées	`SetTitle()`, `SetAuthor()`, `SetSubject()`, `SetKeywords()`, `SetCreator()`	Mappe les setters de métadonnées vers le document sous-jacent.	Garde la normalisation des métadonnées dans le code applicatif.
Pages et positionnement	`AddPage()`, `setPage()`, `lastPage()`, `GetX()`, `SetXY()`	Convertit les unités et coordonnées héritées en opérations de page natives.	Vérifie visuellement le positionnement absolu après la migration.
Marges et mise en page	`SetMargins()`, `SetAutoPageBreak()`, `setCellPaddings()`, `getMargins()`	Stocke l’état de compatibilité et mappe les valeurs prises en charge.	Les comportements complexes de saut de page de TCPDF peuvent nécessiter une revue manuelle.
Polices et texte	`SetFont()`, `AddFont()`, `Cell()`, `MultiCell()`, `Write()`, `Text()`	Achemine les opérations de texte courantes vers les API natives de police et de texte.	Vérifie les comportements CJK et l’encodage avec des polices de production.
HTML	`writeHTML()`, `writeHTMLCell()`, `fixHTMLCode()`	Envoie le HTML pris en charge dans le pipeline HTML natif.	Le moteur de rendu natif n’est pas un clone complet du rendu HTML de TCPDF.
Images et dessin	`Image()`, `Line()`, `Rect()`, `Circle()`, `SetDrawColor()`	Mappe les opérations graphiques prises en charge via les composants de l’adaptateur concernés.	Les formats vectoriels ou spéciaux non pris en charge échouent explicitement.
Navigation et annotations	`Bookmark()`, `AddLink()`, `SetLink()`, `Annotation()`	Préserve les appels de navigation courants quand ils sont mappés.	Valide les sommaires et les liens générés.
Sécurité et signatures	`SetProtection()`, `setSignature()`, `setTimeStamp()`, `setUserRights()`	Fait le pont entre les appels de sécurité hérités pris en charge et les fonctionnalités natives.	Traite la sortie cryptographique comme un point de vérification distinct.
Formulaires, modèles, transformations	`TextField()`, `startTemplate()`, `StartTransform()`, `Rotate()`, `Scale()`	Implémente les sous-ensembles pris en charge et échoue explicitement pour le comportement non pris en charge.	Audite chaque appel avec la couverture des méthodes avant le déploiement.

Amorçage et configuration

Consulte ce tableau au moment de câbler l’adaptateur dans le chemin de démarrage de l’application : enregistrement des alias globaux et choix entre les constantes héritées et le AdaptationConfig moderne.

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
`LegacyBootstrap::enableAliases()`	aucun.	Enregistre une seule fois les alias de compatibilité.	`void`	Erreurs d’autoload ou d’environnement.	À utiliser uniquement quand le code hérité s’attend à ce que les noms TCPDF existent dans l’espace global.
`LegacyBootstrap::isRegistered()`	aucun.	Indique si les alias ont été enregistrés.	`bool`	aucun attendu.	Utile dans les tests d’amorçage.
`LegacyBootstrap::resetForTesting()`	aucun.	Efface l’état d’enregistrement pour les tests.	`void`	aucun attendu.	Aide réservée aux tests.
`AdaptationConfig`	Indicateurs de l’adaptateur et contrôles de migration.	Utilise les valeurs par défaut du package si elle est omise.	`AdaptationConfig`	Valeurs d’options non valides.	Garde la configuration explicite pendant les audits de migration.
`AdaptationConfig::fromLegacyConstants()`	aucun.	Lit les constantes héritées connues et construit la configuration.	`AdaptationConfig`	Valeurs de constante héritée non valides.	Aide transitoire pour les grandes applications héritées.
`LegacyDefaults`	aucun.	Fournit les valeurs héritées par défaut.	Ensemble de valeurs par défaut.	aucun attendu.	Emplacement central pour les valeurs par défaut de compatibilité.

Ponts et aides

Ce sont les classes internes de conversion utilisées par l’adaptateur. Consulte ce tableau surtout quand tu contribues à la couverture de l’adaptateur ou que tu diagnostiques la façon dont un argument hérité a été traduit, pas pour le code applicatif courant.

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
`ConstructorBridge`	Liste des arguments du constructeur hérité.	Normalise les options héritées en configuration NextPDF.	Données du constructeur.	Valeurs d’argument hérité non valides.	Utilisé en interne par l’adaptateur.
`CellParameterAdapter`	Paramètres de cellule TCPDF.	Mappe les arguments positionnels hérités vers les options de mise en page de texte du core.	Paramètres adaptés.	Dimensions ou alignement non valides.	Privilégie les méthodes natives du core dans le nouveau code.
`OutputBridge::dispatch(Document $document, string $filename, string $dest)`	Document natif, nom de fichier et destination héritée.	Mappe le comportement inline/download/enregistrement vers les API de sortie NextPDF.	`string`	Erreurs d’écriture du core ; destination non prise en charge.	Valide les noms de fichiers et les racines de stockage avant la sortie.
`OutputBridge::resolveDestination(string $dest)`	Code de destination hérité.	Convertit la destination en destination de sortie native.	`OutputDestination`	Erreurs de destination non prise en charge.	Garde le mappage des destinations centralisé.
`ColorTranslator`	Arguments de couleur TCPDF.	Normalise les formes de couleur héritées.	Valeur de couleur du core.	Valeurs de couleur non valides.	Utilisé par les responsabilités de couleur et de dessin.
`PageFormatResolver`	Entrée de format de page héritée.	Mappe les noms connus vers les tailles de page du core.	Valeur de format de page.	Format inconnu.	Utilise des tailles de page natives explicites après la migration.
`UnitConverter`	Valeurs et unités de mesure héritées.	Convertit vers les unités du core.	Valeur numérique.	Unité non valide.	Aide à préserver le comportement de mise en page hérité.

Exceptions

Utilise ce tableau quand un appel de migration échoue explicitement. Il t’indique quelle exception correspond à « non implémentée » plutôt qu’à « connue mais non prise en charge », et comment te rétablir dans chaque cas.

Symbole	Sens	Récupération
`TcpdfNotImplementedException`	L’adaptateur n’implémente intentionnellement pas la méthode héritée demandée.	Remplace l’appel par l’API NextPDF native ou supprime la dépendance.
`TcpdfNotImplementedException::forSilentIgnore()`	Un appel hérité aurait été ignoré auparavant, mais il est signalé pour clarifier la migration.	Décide si un comportement no-op explicite est acceptable.
`TcpdfNotImplementedException::forUnimplemented()`	Un appel hérité n’a aucun chemin implémenté via l’adaptateur.	Remplace l’appel ou isole-le derrière du code de migration.
`UnsupportedFeatureException`	La fonctionnalité héritée est connue mais non prise en charge dans le périmètre de l’adaptateur.	Consulte le guide de migration et isole la fonctionnalité derrière un adaptateur applicatif.
`UnsupportedFeatureException::forMethod()`	Crée une erreur de fonctionnalité non prise en charge spécifique à une méthode.	À utiliser dans les contributions de compatibilité pour préserver des messages d’échec cohérents.

Notes de développement

Traite l’adaptateur comme un outil de migration. Le nouveau code devrait cibler directement les API du core de NextPDF.
Le comportement non pris en charge devrait échouer explicitement. N’intercepte pas les exceptions de compatibilité pour continuer avec un document partiel, sauf si l’application accepte explicitement ce risque.
Limite la taille des changements de migration et vérifie chaque méthode héritée avec le tableau de couverture.