Configurer compat-legacy

En un coup d’œil

L’adaptateur expose trois interfaces de configuration :

1. Mode strict — un réglage d’audit qui transforme la perte silencieuse de paramètres en exceptions. Désactivé par défaut.
2. Constantes héritées — les constantes TCPDF K_* / PDF_*, définies automatiquement avec les valeurs par défaut de 6.2.13 pour que le code hérité qui les lit fonctionne.
3. AdaptationConfig — un objet de configuration moderne et immuable qui remplace la configuration fondée sur des constantes.

Tu configures surtout le document via les mêmes méthodes TCPDF que celles que tu appelles déjà (SetMargins(), SetFont(), et ainsi de suite). Les interfaces ci-dessous couvrent ce qui est propre à la couche de compatibilité.

Mode strict

Le mode strict est le réglage le plus important pour une migration. Il ne change pas le rendu généré. Il détermine si un appel qui ne peut pas reproduire le comportement TCPDF échoue explicitement ou se dégrade silencieusement.

examples/config-strict.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();

$pdf->setStrictMode(true);   // audit: throw on silent parameter loss
$isOn = $pdf->isStrictMode(); // true
$pdf->setStrictMode(false);  // back to backward-compatible default

Comportement, tel qu’il est vérifié par tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php :

Mode	Méthode qui ignore silencieusement des paramètres	Résultat
Désactivé (par défaut)	par ex. Image() avec des paramètres supplémentaires	L’appel s’exécute ; les paramètres ignorés n’ont aucun effet
Activé	même appel	Lève TcpdfNotImplementedException en nommant les paramètres ignorés
Activé	une méthode qui ignore silencieusement des paramètres, appelée uniquement avec des paramètres pris en charge	Ne lève pas d’exception (par ex. SetProtection([], 'u', 'o', 0, []))

Le mode strict est additif. Lorsqu’une méthode prend bien en charge un paramètre, la délégation a toujours lieu ; le mode strict se contente d’ajouter un garde-fou qui lève une exception pour les paramètres ignorés. L’usage recommandé est de l’exécuter dans une tâche d’intégration continue dédiée ou lors d’une passe d’audit ponctuelle, pas en production. La logique suit le principe de l’échec explicite de la gestion des erreurs OWASP ASVS 5.0 (clause reference_id enregistrée dans le sidecar RAG) : un appelant doit pouvoir constater quand son intention n’a pas été honorée.

N’expédie pas de code de production avec le mode strict activé. Un paramètre silencieusement ignoré est un problème d’expérience développeur, pas une erreur d’exécution, et une exception dans un chemin de rendu de production est pire que la sortie dégradée. Audite, corrige, puis désactive-le — voir /integrations/tcpdf-compat/migration/.

Constantes TCPDF héritées

Le code TCPDF hérité lit la configuration dans les constantes K_* et PDF_*. L’adaptateur les définit automatiquement à la construction seulement si elles ne sont pas déjà définies, en utilisant les valeurs par défaut de TCPDF 6.2.13. Si ton application définit déjà une constante (par exemple un K_PATH_FONTS personnalisé), ta valeur est préservée.

Sélection de valeurs par défaut (liste complète : src/Compat/Tcpdf/Config/LegacyDefaults.php) :

Constante	Valeur par défaut	Remarque
PDF_PAGE_FORMAT	A4
PDF_PAGE_ORIENTATION	P
PDF_UNIT	mm
PDF_MARGIN_LEFT / RIGHT	15	unités utilisateur
PDF_MARGIN_TOP	27	unités utilisateur
PDF_MARGIN_BOTTOM	25	unités utilisateur
PDF_FONT_NAME_MAIN	helvetica
PDF_FONT_SIZE_MAIN	10
K_CELL_HEIGHT_RATIO	1.25
K_TCPDF_CALLS_IN_HTML	false	durci — toujours faux ; le balisage ne peut pas déclencher l’exécution de PHP
K_TCPDF_THROW_EXCEPTION_ERROR	true	durci — Error() lève toujours une exception ; jamais die()
K_TIMEZONE	UTC

Deux d’entre elles sont délibérément figées pour des raisons de sécurité et ne peuvent pas être assouplies via la configuration : K_TCPDF_CALLS_IN_HTML est toujours false, et K_TCPDF_THROW_EXCEPTION_ERROR est effectivement toujours true. Si du code hérité dépend de l’un ou l’autre des comportements hérités non sûrs, ce code doit changer — voir /integrations/tcpdf-compat/security-and-operations/.

Pour définir tes propres constantes, fais-le avant de construire l’adaptateur pour la première fois (généralement dans l’amorçage de ton application) :

examples/config-constants.php

<?php

declare(strict_types=1);

// Define BEFORE constructing the adapter; the adapter will not override it.
define('PDF_CREATOR', 'My Application');
define('PDF_AUTHOR', 'My Application');

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
// Creator and Author are seeded from your constants.

L’objet moderne AdaptationConfig

Pour le code qui ne veut pas dépendre de constantes globales, le paquet fournit un objet-valeur de configuration immuable, NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Il est final readonly et chaque champ prend par défaut la valeur de TCPDF 6.2.13. Tu peux l’instancier sans risque en ne renseignant que les champs que tu veux modifier.

Tu peux aussi le construire à partir des constantes héritées actuellement définies :

examples/config-adaptation.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Config\AdaptationConfig;

// Snapshot the currently-defined legacy constants into an object:
$config = AdaptationConfig::fromLegacyConstants();

echo $config->pageFormat;   // 'A4' unless a constant overrides it
echo $config->fontNameMain; // 'helvetica'
echo $config->marginLeft;   // 15.0

AdaptationConfig est la cible de migration pour la configuration. À mesure que tu déplaces les points d’appel vers l’API moderne, remplace les consultations de constantes par des champs AdaptationConfig explicites, afin que la configuration soit typée et locale plutôt que globale.

Ordre de résolution de la configuration

Lorsque l’adaptateur construit un document, la configuration est résolue dans cet ordre (les étapes suivantes ne remplacent pas les précédentes) :

1. Arguments du constructeur (orientation, unit, format, …) — priorité la plus élevée pour les valeurs qu’ils couvrent.
2. Constantes héritées préexistantes définies par l’application.
3. Constantes par défaut de TCPDF 6.2.13, définies automatiquement par LegacyDefaults pour toute constante non encore définie.

Les arguments du constructeur unicode, encoding et diskcache sont acceptés pour la compatibilité de signature et n’ont aucun effet. NextPDF est toujours Unicode et UTF-8, et n’a pas de cache de pages sur disque. L’argument de constructeur pdfa est lui aussi accepté, mais la conformité d’archivage PDF/A requiert une édition commerciale (voir /integrations/tcpdf-compat/security-and-operations/).

Voir aussi

• src/Compat/Tcpdf/Config/LegacyDefaults.php — source de référence des valeurs par défaut des constantes
• src/Compat/Tcpdf/Config/AdaptationConfig.php — objet de configuration moderne
• /integrations/tcpdf-compat/migration/ — déplacer la configuration hors des constantes globales
• /integrations/tcpdf-compat/security-and-operations/ — les deux drapeaux durcis et non configurables