Démarrage rapide compat-legacy

En bref

Cette page te guide depuis le paquet installé jusqu’à la génération d’un PDF, puis jusqu’à l’audit en mode strict à exécuter avant la migration. Chaque bloc de code correspond à un comportement vérifié par la suite de tests du paquet ; la sortie présentée ici est donc exactement celle que les tests contrôlent.

Avant de commencer

Installe le paquet et vérifie son intégration avec le moteur en suivant /integrations/tcpdf-compat/install/. Il te faut PHP 8.4, et nextpdf/core ^3.0 doit être résolu.

1. Produis ton premier document

Modifie l’import et conserve tes appels de style TCPDF. C’est précisément 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->SetCreator('Quickstart');
$pdf->SetTitle('First Document');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

Exécute-le :

php examples/quickstart-first.php

Le fichier quickstart.pdf est un PDF 2.0 valide. La suite de tests vérifie que la sortie équivalente sous forme de chaîne commence par %PDF pour les destinations S, F et E, ainsi que pour getPDFData().

Destinations de sortie

Output($name, $dest) fait correspondre les codes de destination TCPDF via un pont de sortie sûr. Voici le comportement validé par la suite de tests :

`$dest`	Comportement	Retourne
`'S'`	Retourne le PDF sous forme de chaîne	les octets du PDF (`%PDF…`)
`'F'`	Écrit le PDF au chemin indiqué	chaîne vide
`'E'`	Retourne un corps MIME en base64	un bloc `Content-Type: application/pdf`
`'I'`	Affichage en ligne (par défaut)	selon le pont de sortie
`'D'`	Téléchargement	selon le pont de sortie

Contrairement à l’ancien TCPDF, Output() n’écrit pas directement dans le tampon de sortie actif ; tu peux donc l’appeler sans risque depuis un worker de file d’attente ou un gestionnaire HTTP qui contrôle sa propre réponse. Voir /integrations/tcpdf-compat/production-usage/.

2. Exécute du code TCPDF existant sans le modifier

Pour une vraie migration, commence par exécuter ton code existant en ne modifiant que l’import ou l’alias. Si ta base de code appelle new \TCPDF(...) dans l’espace de noms global, active les alias optionnels une seule fois au démarrage (décrits dans /integrations/tcpdf-compat/boot-and-discovery/) :

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

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

LegacyBootstrap::enableAliases() est idempotent. Il enregistre \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS et \TCPDF_IMAGES uniquement si ces classes n’existent pas déjà. Le test du paquet tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php vérifie que les alias s’enregistrent, que l’appel est idempotent et que new \TCPDF() est une instance de l’adaptateur. N’active pas les alias si la véritable bibliothèque TCPDF est chargée dans le même processus — voir /integrations/tcpdf-compat/troubleshooting/.

3. Audite avec le mode strict

C’est l’étape qui rend la migration sûre. Avec le mode strict désactivé (le comportement par défaut), les méthodes qui ne peuvent pas reproduire le comportement de TCPDF se dégradent silencieusement. Avec le mode strict activé, elles lèvent TcpdfNotImplementedException en indiquant exactement les paramètres ignorés. Exécute cette passe d’audit dédiée, jamais en production.

<?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 {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

Le test du paquet tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php vérifie que cet appel précis lève une exception en mode strict, qu’il reste silencieux en mode par défaut, et que le message contient le nom de la méthode et les paramètres ignorés. Utilise les exceptions collectées comme liste de travail pour la migration — voir /integrations/tcpdf-compat/migration/.

4. Accède à l’API moderne quand tu en as besoin

Chaque instance de l’adaptateur expose le document du moteur sous-jacent. Sers-t’en pour appeler les méthodes modernes de NextPDF qui n’ont pas d’équivalent TCPDF :

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument() retourne le NextPDF\Core\Document que l’adaptateur encapsule. C’est la voie de sortie recommandée : migre tes points d’appel vers l’API moderne un par un, jusqu’à pouvoir supprimer l’adaptateur.

Différences de comportement à anticiper d’emblée

MultiCell() retourne 1, et non le nombre de cellules rendues. Le code qui choisit une branche selon la valeur de retour de MultiCell() doit être ajusté.
Error() lève RuntimeException au lieu d’appeler die(). Le code qui reposait sur l’arrêt du processus doit intercepter l’exception.
Les octets exacts du PDF diffèrent de la sortie de TCPDF. Réétalonne les assertions de test au niveau des octets pour qu’elles portent plutôt sur le contenu rendu.

La liste complète, méthode par méthode, figure dans /integrations/tcpdf-compat/method-coverage/.

Étapes suivantes

/integrations/tcpdf-compat/migration/ — la stratégie complète de migration, fichier par fichier.
/integrations/tcpdf-compat/configuration/ — le mode strict, les valeurs par défaut et l’objet de configuration moderne.
/integrations/tcpdf-compat/production-usage/ — les workers, les tampons de sortie et les performances.
/integrations/tcpdf-compat/security-and-operations/ — la posture de chiffrement et de signature.

Voir aussi

tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — oracle du comportement de sortie
tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — oracle du mode strict
docs/TCPDF_COVERAGE.md — matrice de couverture de référence