Amorçage et découverte de NextPDF compat-legacy

En un coup d’œil

nextpdf/compat-legacy expose une façade compatible TCPDF — la classe NextPDF\Compat\Tcpdf\TCPDF — qui délègue les opérations au moteur NextPDF. C’est une couche de compatibilité, pas un clone interchangeable. Elle couvre, par délégation directe, 94 des quelque 120 méthodes TCPDF 6.x recensées. Les méthodes restantes présentent des différences de comportement documentées (voir /integrations/tcpdf-compat/method-coverage/).

Il n’y a aucun câblage global au moment de l’autoload. Par défaut, charger le paquet ne crée pas de classe globale \TCPDF. Tu actives les alias globaux explicitement ou — option à privilégier pendant la migration — tu importes la classe d’adaptation fichier par fichier.

Comment la façade TCPDF est exposée

La façade est une classe ordinaire, chargée automatiquement via PSR-4 :

Élément	Valeur
Classe de façade	NextPDF\Compat\Tcpdf\TCPDF
Préfixe PSR-4	NextPDF\Compat\Tcpdf\ correspond à src/Compat/Tcpdf/
Contrat partagé	NextPDF\Compat\Contracts\CompatAdapterInterface
Échappatoire	TCPDF::getDocument() renvoie le NextPDF\Core\Document encapsulé

La classe n’est volontairement pas final : dans les bases de code TCPDF historiques, il est courant de sous-classer TCPDF pour redéfinir Header() et Footer(), et l’adaptateur préserve donc ce point d’extension. En interne, la classe est une façade : elle compose 25 traits à responsabilité unique et délègue toutes les opérations PDF à une instance Document construite au moment de la génération.

Séquence d’amorçage

Diagram

La construction est la seule étape d’« amorçage ». Le paquet lui-même n’enregistre rien dans un conteneur de services et n’amorce aucun framework. L’intégration au framework est une fine couche que tu ajoutes — voir /integrations/tcpdf-compat/integration/.

LegacyDefaults::register() est idempotente : elle ne définit une constante que si celle-ci n’est pas déjà définie. Les constantes définies par l’application l’emportent toujours, à condition que tu les définisses avant la première construction (voir /integrations/tcpdf-compat/configuration/ § Ordre de résolution de la configuration).

Alias de classes globales facultatifs

Si ton code appelle new \TCPDF(...) dans l’espace de noms global et que tu ne peux pas encore modifier ces sites d’appel, enregistre les alias globaux une seule fois à l’amorçage de l’application :

examples/boot-aliases.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() enregistre \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS et \TCPDF_IMAGES. Le comportement, vérifié par tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php, est le suivant :

• enableAliases() est idempotente — deux appels successifs ne lèvent pas d’exception et l’enregistrement n’a lieu qu’une seule fois.
• LegacyBootstrap::isRegistered() indique si l’enregistrement a été effectué.
• Après l’enregistrement, new \TCPDF() produit une instance de l’adaptateur.

Éviter les conflits avec une véritable installation de TCPDF

C’est la règle la plus importante de cette page.

enableAliases() enregistre un alias uniquement si une classe portant ce nom n’existe pas déjà (class_exists($alias, autoload: false)). Par conséquent :

• Si tecnickcom/tcpdf est installé et que son \TCPDF est chargé en premier, l’alias est ignoré silencieusement et ton code continue d’utiliser le TCPDF historique — pas l’adaptateur.
• Faire cohabiter les deux bibliothèques avec les alias globaux activés dans le même processus n’est pas pris en charge et produit un comportement ambigu.

Pendant la migration, privilégie les imports explicites fichier par fichier (use NextPDF\Compat\Tcpdf\TCPDF;). Ils sont repérables par grep et sans ambiguïté. Supprime tecnickcom/tcpdf une fois que l’audit en mode strict est validé (voir /integrations/tcpdf-compat/migration/ Étape 5). Quand \TCPDF se résout vers la mauvaise classe, /integrations/tcpdf-compat/troubleshooting/ fournit le diagnostic.

Liaisons de conteneur

Le paquet ne fournit aucune liaison pour un conteneur de framework. Si tu lies la façade dans un conteneur, déclare une fabrique qui renvoie un nouveau NextPDF\Compat\Tcpdf\TCPDF par document. L’état du document est propre à chaque instance et ne doit pas être partagé entre des documents distincts (voir /integrations/tcpdf-compat/production-usage/ § Concurrence). Une liaison typique est présentée dans /integrations/tcpdf-compat/integration/.

Ordre de résolution de la configuration

À la construction, l’adaptateur résout la configuration dans cet ordre : d’abord les arguments du constructeur, puis les constantes historiques déjà définies par l’application, le cas échéant, et enfin les valeurs par défaut TCPDF 6.2.13 de LegacyDefaults pour toute constante qui n’est pas déjà définie. Pour le détail complet et l’objet AdaptationConfig moderne, voir /integrations/tcpdf-compat/configuration/.

Diagnostics

Pour vérifier que la façade est câblée et que le lien vers le moteur se résout, construis un adaptateur et produis un PDF d’une page, puis contrôle le préfixe %PDF. Ce contrôle couvre la même surface que les tests de sortie du paquet. Le contrôle exécutable se trouve dans /integrations/tcpdf-compat/install/ § Vérifier l’installation.

Pour détecter un conflit avec un véritable TCPDF avant d’activer les alias, vérifie si un \TCPDF global existe déjà à l’endroit où tu appellerais enableAliases(). Si c’est le cas, un alias sera ignoré ; résous donc le conflit (utilise des imports explicites ou supprime le véritable TCPDF) avant de t’appuyer sur l’adaptateur.

Couverture de l’API TCPDF

La matrice de couverture de référence, vérifiée par les tests, est le fichier interne au dépôt docs/TCPDF_COVERAGE.md. Le résumé destiné aux lecteurs, y compris les listes des méthodes ignorées silencieusement et non implémentées, se trouve dans /integrations/tcpdf-compat/method-coverage/. Ce paquet ne prétend ni être un « remplacement interchangeable » ni être « 100 % compatible TCPDF » ; c’est une alternative compatible TCPDF, avec une surface de compatibilité connue et testée ainsi que des différences de comportement documentées.

Voir aussi

• docs/TCPDF_COVERAGE.md — source de couverture de référence (interne au dépôt)
• /integrations/tcpdf-compat/integration/ — câbler la façade dans une application/framework
• /integrations/tcpdf-compat/method-coverage/ — comportement et lacunes méthode par méthode
• /integrations/tcpdf-compat/migration/ — stratégie de migration par étapes
• /integrations/tcpdf-compat/troubleshooting/ — diagnostic du conflit alias/real-TCPDF
• tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — oracle du comportement des alias