Configurar compat-legacy

De un vistazo

El adaptador expone tres superficies de configuración:

1. Modo estricto — un conmutador de auditoría que convierte la pérdida silenciosa de parámetros en excepciones. Desactivado de forma predeterminada.
2. Constantes heredadas — las constantes K_* / PDF_* de TCPDF, definidas automáticamente con los valores predeterminados de 6.2.13 para que funcione el código heredado que las lee.
3. AdaptationConfig — un objeto de configuración moderno e inmutable que reemplaza la configuración basada en constantes.

El documento se configura principalmente mediante los mismos métodos de TCPDF que ya se utilizan (SetMargins(), SetFont(), etc.). Las superficies descritas a continuación cubren únicamente lo específico de la capa de compatibilidad.

Modo estricto

El modo estricto es el ajuste más importante durante una migración. No cambia la representación de salida. Controla si una llamada que no puede reproducir el comportamiento de TCPDF falla de forma explícita o se degrada de forma silenciosa.

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

Comportamiento, según lo verificado por tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php:

Modo	Método con omisión silenciosa invocado	Resultado
Desactivado (predeterminado)	p. ej. Image() con parámetros adicionales	Se ejecuta; los parámetros ignorados no tienen efecto
Activado	la misma llamada	Lanza TcpdfNotImplementedException nombrando los parámetros ignorados
Activado	un método con omisión silenciosa invocado solo con parámetros admitidos	no lanza (p. ej. SetProtection([], 'u', 'o', 0, []))

El modo estricto es aditivo. Cuando un método sí admite un parámetro, esa delegación sigue ocurriendo; el modo estricto solo añade una comprobación de excepción para los parámetros que se descartan. El uso recomendado es ejecutarlo en un trabajo de CI dedicado o en una pasada de auditoría puntual, no en producción. El razonamiento sigue el principio de fallar de forma explícita del manejo de errores de OWASP ASVS 5.0 (cláusula reference_id registrada en el sidecar de RAG): quien realiza la llamada debe poder observar cuándo no se ha respetado su intención.

No desplegar código de producción con el modo estricto activado. Un parámetro ignorado de forma silenciosa es un problema de experiencia del desarrollador, no un fallo en tiempo de ejecución, y una excepción en una ruta de representación de producción resulta peor que la salida degradada. Auditar, corregir y luego desactivarlo — consulte /integrations/tcpdf-compat/migration/.

Constantes heredadas de TCPDF

TCPDF heredado lee la configuración de las constantes K_* y PDF_*. El adaptador las define automáticamente durante la construcción solo si aún no están definidas, usando los valores predeterminados de TCPDF 6.2.13. Si la aplicación ya define una constante (por ejemplo, una K_PATH_FONTS personalizada), su valor se conserva.

Selección de valores predeterminados (lista completa: src/Compat/Tcpdf/Config/LegacyDefaults.php):

Constante	Predeterminado	Nota
PDF_PAGE_FORMAT	A4
PDF_PAGE_ORIENTATION	P
PDF_UNIT	mm
PDF_MARGIN_LEFT / RIGHT	15	unidades de usuario
PDF_MARGIN_TOP	27	unidades de usuario
PDF_MARGIN_BOTTOM	25	unidades de usuario
PDF_FONT_NAME_MAIN	helvetica
PDF_FONT_SIZE_MAIN	10
K_CELL_HEIGHT_RATIO	1.25
K_TCPDF_CALLS_IN_HTML	false	reforzado — siempre false; el marcado no puede desencadenar la ejecución de PHP
K_TCPDF_THROW_EXCEPTION_ERROR	true	reforzado — Error() siempre lanza; nunca die()
K_TIMEZONE	UTC

Dos de estas constantes se fijan deliberadamente por seguridad y no se pueden relajar mediante la configuración: K_TCPDF_CALLS_IN_HTML es siempre false, y K_TCPDF_THROW_EXCEPTION_ERROR es efectivamente siempre true. Si el código heredado depende de cualquiera de esos comportamientos heredados inseguros, ese código debe cambiar — consulte /integrations/tcpdf-compat/security-and-operations/.

Para definir constantes propias, definirlas antes de la primera construcción del adaptador (normalmente en el arranque de la aplicación):

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.

El objeto AdaptationConfig moderno

Para el código que no quiera depender de constantes globales, el paquete proporciona un objeto de valor de configuración inmutable, NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Es final readonly y cada campo toma como valor predeterminado el valor de TCPDF 6.2.13. Se puede construir de forma segura especificando solo los campos que se quieran cambiar.

También se puede construir a partir de cualquier constante heredada que esté definida en ese momento:

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 es el destino de migración para la configuración. A medida que se trasladen los puntos de llamada a la API moderna, reemplazar las búsquedas de constantes por campos explícitos de AdaptationConfig, de modo que la configuración sea tipada y local en lugar de global.

Orden de resolución de la configuración

Cuando el adaptador crea un documento, la configuración se resuelve en este orden (los pasos posteriores no anulan los anteriores):

1. Argumentos del constructor (orientation, unit, format, …) — máxima precedencia para los valores que cubren.
2. Constantes heredadas preexistentes definidas por la aplicación.
3. Constantes predeterminadas de TCPDF 6.2.13, definidas automáticamente por LegacyDefaults para cualquier constante que aún no esté definida.

Los argumentos del constructor unicode, encoding y diskcache se aceptan por compatibilidad con la firma y no tienen efecto. NextPDF es siempre Unicode y UTF-8, y no tiene caché de páginas en disco. La marca del constructor pdfa también se acepta, pero la conformidad de archivado PDF/A requiere una edición comercial (consulte /integrations/tcpdf-compat/security-and-operations/).

Consulte también

• src/Compat/Tcpdf/Config/LegacyDefaults.php — valores predeterminados autoritativos de constantes
• src/Compat/Tcpdf/Config/AdaptationConfig.php — objeto de configuración moderno
• /integrations/tcpdf-compat/migration/ — trasladar la configuración fuera de las constantes globales
• /integrations/tcpdf-compat/security-and-operations/ — las dos marcas reforzadas y no configurables