Intégration de NextPDF compat-legacy

En bref

Cette page explique comment brancher nextpdf/compat-legacy dans une application afin que le code TCPDF 6.x existant s’exécute sur le moteur NextPDF. Le paquet est une aide à la migration, pas un correctif permanent : l’objectif est de le retirer une fois l’API moderne adoptée (voir /integrations/tcpdf-compat/migration/). C’est une alternative compatible TCPDF, pas un clone interchangeable : 94 des quelque 120 méthodes TCPDF recensées délèguent directement. Les autres présentent des différences de comportement documentées (voir /integrations/tcpdf-compat/method-coverage/).

Installation

composer require nextpdf/compat-legacy:^3.0

Cela résout transitivement nextpdf/core ^3.0. Exigences complètes et vérification de contrôle : /integrations/tcpdf-compat/install/.

Amorçage et découverte automatique

Il n’y a aucun branchement global au moment du chargement automatique. Le simple fait d’inclure le paquet ne crée pas de \TCPDF global. Tu choisis comment les sites d’appel résolvent la classe :

Recommandé (imports explicites). Remplace les lignes use/require par use NextPDF\Compat\Tcpdf\TCPDF; dans chaque fichier. C’est explicite et facile à repérer avec grep.
Alias globaux optionnels. Appelle LegacyBootstrap::enableAliases() une fois à l’amorçage pour enregistrer \TCPDF et les quatre classes auxiliaires — uniquement si ces noms ne sont pas déjà pris. Mécanisme, idempotence et règle de conflit avec le TCPDF réel : /integrations/tcpdf-compat/boot-and-discovery/.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

// One call at application bootstrap, before any \TCPDF use.
LegacyBootstrap::enableAliases();

Liaisons du conteneur

Le paquet ne fournit ni fournisseur de services ni bundle de framework. L’intégration est une fine couche que tu contrôles. Lie une fabrique qui renvoie un nouvel adaptateur par document — jamais un singleton partagé, car l’état du document est propre à chaque instance (voir /integrations/tcpdf-compat/production-usage/ § Concurrence).

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use Psr\Container\ContainerInterface;

// Pseudocode for a PSR-11-style container: bind a factory, not a shared instance.
$container->set(TCPDF::class, static function (ContainerInterface $c): TCPDF {
    return new TCPDF('P', 'mm', 'A4');
});

// Each resolution is an independent document context.
$pdf = $container->get(TCPDF::class);

Pour Symfony, enregistre la fabrique comme service non partagé. Pour Laravel, lie-la avec bind (pas singleton) afin que chaque résolution crée une nouvelle instance. Le paquet lui-même reste indépendant de tout framework.

Publication de la configuration

Il n’existe aucun fichier de configuration de framework publiable. Configure avec les constantes héritées K_* / PDF_* (définis-les dans ton amorçage avant la première construction) ou avec l’objet immuable moderne NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Voir /integrations/tcpdf-compat/configuration/.

Test de fumée du fournisseur de services / bundle

Une fois le branchement effectué, vérifie que l’intégration produit un PDF valide. Cela reflète la surface vérifiée par tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php :

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Integration smoke test');

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

assert(str_starts_with($bytes, '%PDF'), 'Integration smoke test failed');
echo "Integration OK\n";

Dans un contexte HTTP ou worker, utilise Output(..., 'F') ou 'S'. Ne te fie pas au mode inline. Les recommandations opérationnelles complètes se trouvent dans /integrations/tcpdf-compat/production-usage/.

Points d’entrée de l’API publique

Point d’entrée	Rôle
`NextPDF\Compat\Tcpdf\TCPDF`	La façade compatible TCPDF. À construire pour chaque document.
`TCPDF::getDocument()`	Renvoie le `NextPDF\Core\Document` encapsulé : l’échappatoire vers l’API moderne.
`TCPDF::setStrictMode(bool)`	Commutateur d’audit de migration (voir /integrations/tcpdf-compat/configuration/).
`NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()`	Alias de classes globaux optionnels.
`NextPDF\Compat\Tcpdf\Config\AdaptationConfig`	Objet de configuration moderne et immuable.
`NextPDF\Compat\Contracts\CompatAdapterInterface`	Contrat de compatibilité partagé.

Couverture de l’API TCPDF

La matrice de couverture de référence, vérifiée par les tests, est le fichier docs/TCPDF_COVERAGE.md présent dans le dépôt. Le résumé destiné au lecteur — méthodes reproduites, ignorées en silence, non implémentées et non applicables — se trouve dans /integrations/tcpdf-compat/method-coverage/. Aucune prétention de « remplacement interchangeable » ni de « 100 % compatible » n’est avancée. La description exacte est celle d’une alternative compatible TCPDF, avec une surface 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 (dans le dépôt)
/integrations/tcpdf-compat/boot-and-discovery/ — exposition de la façade et mécanisme d’alias
/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/production-usage/ — exécution de l’adaptateur en charge
tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — oracle de comportement de sortie