Dépannage de compat-legacy

En un coup d’œil

La plupart des problèmes de migration relèvent d’un petit nombre de schémas récurrents. Chaque cas ci-dessous précise le symptôme, la cause et le correctif. En cas de doute sur une méthode précise, consulte /integrations/tcpdf-compat/method-coverage/ et la matrice de référence dans le dépôt docs/TCPDF_COVERAGE.md.

Le processus s’arrêtait sur une erreur PDF ; désormais une exception remonte

Symptôme. Le code qui s’interrompait auparavant en cas d’échec de rendu lève désormais une RuntimeException non capturée, et la requête ou la tâche fait remonter une erreur.

Cause. Dans TCPDF, l’ancien Error() appelle die(). L’adaptateur lève plutôt une RuntimeException — par conception, afin que les échecs soient observables.

Correctif. Encadre les points d’entrée du rendu par try/catch et fais correspondre l’exception à ton contrat d’erreur. Ne rétablis pas le comportement de die(). Voir /integrations/tcpdf-compat/production-usage/ § Gestion des échecs.

`new \TCPDF()` pointe toujours vers la vraie bibliothèque TCPDF

Symptôme. Tu as activé LegacyBootstrap::enableAliases(), mais la sortie ressemble toujours à celle de l’ancien TCPDF, ou le comportement n’a pas changé.

Cause. enableAliases() n’enregistre un alias que si aucune classe portant ce nom n’existe déjà. Si tecnickcom/tcpdf reste disponible via l’autoload et que son \TCPDF est chargé en premier, l’alias est ignoré et ton code continue d’utiliser l’ancien TCPDF.

Correctif. Pendant la migration, privilégie les imports explicites dans chaque fichier (use NextPDF\Compat\Tcpdf\TCPDF;) pour que chaque site d’appel soit sans ambiguïté. Supprime tecnickcom/tcpdf une fois l’audit réussi (voir /integrations/tcpdf-compat/migration/ étape 5). N’exécute pas les deux bibliothèques dans le même processus avec les alias globaux activés.

Une méthode « fonctionne » mais le paramètre que j’ai passé est ignoré

Symptôme. Un appel aboutit et produit un PDF, mais une option que tu as passée (lien d’image, alignement, DPI, couleur de signet, …) reste sans effet.

Cause. La méthode appartient à l’ensemble des appels à paramètres ignorés silencieusement. Elle accepte le paramètre pour préserver la compatibilité du code source, puis l’ignore. C’est un comportement documenté, pas un bogue — voir /integrations/tcpdf-compat/method-coverage/ §2.

Correctif. Lance un audit en mode strict pour repérer chacun de ces appels :

<?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('logo.png', 10, 10, 50, 0, '', 'https://example.com');
} catch (TcpdfNotImplementedException $e) {
    // Message lists every ignored parameter and a migration hint.
    echo $e->getMessage(), "\n";
}

Supprime ensuite le paramètre ou exprime-le autrement via l’API moderne ($pdf->getDocument()), comme indiqué à l’étape 4 de /integrations/tcpdf-compat/migration/.

La valeur de retour de `MultiCell()` vaut toujours 1

Symptôme. Le code qui prend une branche selon la valeur de retour de MultiCell() (par exemple pour calculer la hauteur utilisée ou le nombre de lignes) se comporte mal.

Cause. Le MultiCell() de l’adaptateur renvoie la valeur réservée de compatibilité 1, et non le nombre de cellules/lignes rendues. De même, Write() renvoie 0.

Correctif. Ne base pas ta logique de branchement sur ces valeurs de retour. Si tu as besoin de la hauteur rendue, calcule-la à partir de getStringHeight() / getNumLines(), ou déplace cette logique vers l’API moderne.

`setPDFVersion('1.4')` n’a pas produit de fichier PDF 1.4

Symptôme. Tu as demandé une version de PDF plus ancienne ; la sortie reste en PDF 2.0.

Cause. La sortie est toujours générée en PDF 2.0 (ISO 32000-2). setPDFVersion() fait partie de l’ensemble non applicable ; l’adaptateur émet un avertissement et poursuit.

Correctif. Supprime l’appel. Si un consommateur en aval exige une version de PDF plus ancienne, résous cette contrainte du consommateur séparément ; l’adaptateur ne peut pas cibler une version inférieure.

`setSignature()` n’a rien fait — le PDF n’est pas signé

Symptôme. Tu as appelé setSignature() avec un certificat ; le PDF de sortie n’a aucune signature.

Cause. setSignature() n’est pas implémentée sur le moteur central via cet adaptateur. En mode par défaut, c’est une opération nulle ; en mode strict, elle lève une exception.

Correctif. La signature requiert une édition commerciale de NextPDF et l’API de signature moderne. Voir /integrations/tcpdf-compat/security-and-operations/ § Signatures numériques. N’attends pas de l’ancien appel setSignature() qu’il signe quoi que ce soit.

`Output()` a corrompu ma réponse HTTP ou la sortie de mon worker

Symptôme. Des données binaires parasites apparaissent dans une réponse HTTP, ou un journal de worker est pollué par des octets de PDF.

Cause. Tu as utilisé une destination de sortie qui écrit sur le flux de sortie (I/D) dans un contexte où tu contrôles toi-même la réponse. L’adaptateur n’écrit pas dans ton tampon comme le fait l’ancien TCPDF, mais I/D pilotent toujours la sortie du moteur.

Correctif. Dans les workers et les gestionnaires que tu contrôles, utilise Output($path, 'F') pour écrire un fichier, ou Output($name, 'S') pour récupérer les octets et les émettre toi-même. La correspondance des destinations (insensible à la casse, espaces supprimés) est vérifiée dans tests/Unit/Compat/Tcpdf/Bridge/OutputBridgeTest.php :

Code	Retourne	Effet de bord
`S`	Octets de PDF (`%PDF…`)	aucun
`F`	chaîne vide	écrit le fichier
`E`	corps MIME en base64	aucun
`FI` / `FD`	chaîne vide	écrit le fichier, puis sortie du moteur
`I` / `D` / inconnu	chaîne vide	sortie du moteur (en ligne/téléchargement)

Les assertions PDF octet par octet échouent après le basculement

Symptôme. Les tests de capture qui comparent les octets bruts du PDF échouent tous.

Cause. Le moteur est une implémentation indépendante de PDF 2.0. Le rendu visible reste compatible pour les méthodes déléguées, mais les octets diffèrent. C’est le comportement attendu.

Correctif. Mets à jour la référence pour valider le contenu rendu (texte extrait), la structure (nombre de pages, taille de page) ou un contrôle rapide (str_starts_with($bytes, '%PDF')). Voir l’étape 4 de /integrations/tcpdf-compat/migration/.

Une ancienne constante `K_` / `PDF_` a la mauvaise valeur

Symptôme. Un chemin personnalisé ou une valeur par défaut que tu as définie via une constante ne prend pas effet.

Cause. L’adaptateur ne définit automatiquement une constante que si elle n’est pas déjà définie, et il le fait lors de la première construction. Si ton define() s’exécute après la construction du premier adaptateur, la valeur par défaut de l’adaptateur l’a déjà emporté.

Correctif. Définis toutes tes constantes K_* / PDF_* personnalisées dans ton bootstrap, avant toute création d’instance d’adaptateur. Voir /integrations/tcpdf-compat/configuration/ § Ordre de résolution de la configuration.

Incompatibilité de version du moteur lors de la construction

Symptôme. La construction échoue ou adopte un comportement inattendu après une mise à jour de dépendance.

Cause. L’adaptateur requiert nextpdf/core ^3.0. Une version du cœur résolue en dehors de cette plage n’est pas prise en charge.

Correctif. Lance composer show nextpdf/core et épingle le moteur à ^3.0. Voir /integrations/tcpdf-compat/install/ § Vérifier la version du moteur.

Aide-mémoire de diagnostic

Question	Où regarder
Que fait réellement la méthode X ici ?	/integrations/tcpdf-compat/method-coverage/, `docs/TCPDF_COVERAGE.md`
Lesquels de mes appels perdent des paramètres ?	Audit en mode strict (cette page ; /integrations/tcpdf-compat/migration/)
Pourquoi le processus ne s’est-il pas arrêté sur l’erreur ?	/integrations/tcpdf-compat/security-and-operations/ § Comportements renforcés
Pourquoi la sortie n’est-elle pas signée / pas en PDF/A ?	/integrations/tcpdf-compat/security-and-operations/
Conflit entre alias et import explicite	Cette page ; /integrations/tcpdf-compat/boot-and-discovery/

Voir aussi

/integrations/tcpdf-compat/migration/ — la migration par étapes qui évite la plupart des problèmes ci-dessus
/integrations/tcpdf-compat/method-coverage/ — référence du comportement par méthode
/integrations/tcpdf-compat/boot-and-discovery/ — enregistrement des alias et prévention des conflits
docs/TCPDF_COVERAGE.md — matrice de couverture de référence

Dépannage de compat-legacy

En un coup d’œil

Le processus s’arrêtait sur une erreur PDF ; désormais une exception remonte

new \TCPDF() pointe toujours vers la vraie bibliothèque TCPDF