Configurazione di compat-legacy

In sintesi

L’adattatore espone tre superfici di configurazione:

Modalità rigorosa — un controllo di verifica che trasforma la perdita silenziosa di parametri in eccezioni. Disattivata per impostazione predefinita.
Costanti legacy — le costanti TCPDF K_* / PDF_*, definite automaticamente con i valori predefiniti 6.2.13 affinché il codice legacy che le legge continui a funzionare.
AdaptationConfig — un oggetto di configurazione moderno e immutabile che sostituisce la configurazione basata su costanti.

La configurazione del documento avviene per lo più tramite gli stessi metodi TCPDF già utilizzati (SetMargins(), SetFont() e così via). Le sezioni seguenti coprono ciò che riguarda in modo specifico il livello di compatibilità.

Modalità rigorosa

La modalità rigorosa è l’impostazione più importante durante una migrazione. Non modifica l’output del rendering. Stabilisce se una chiamata che non può riprodurre il comportamento di TCPDF fallisce in modo esplicito oppure degrada silenziosamente.

<?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

Comportamento, come verificato da tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php:

Modalità	Metodo richiamato che ignora silenziosamente	Risultato
Disattivata (predefinita)	per es. `Image()` con parametri aggiuntivi	Viene eseguito; i parametri ignorati non hanno alcun effetto
Attiva	la stessa chiamata	Solleva `TcpdfNotImplementedException` indicando i parametri ignorati
Attiva	un metodo che può ignorare silenziosamente parametri, richiamato solo con parametri supportati	Non solleva alcuna eccezione (per es. `SetProtection([], 'u', 'o', 0, [])`)

La modalità rigorosa è additiva. Quando un metodo supporta effettivamente un parametro, la delega continua ad avvenire; la modalità rigorosa aggiunge soltanto una protezione tramite eccezione per i parametri che vengono scartati. L’uso consigliato è un processo di CI dedicato o una verifica una tantum, non la produzione. La logica segue il principio del fallimento esplicito nella gestione degli errori di OWASP ASVS 5.0 (clausola reference_id registrata nel sidecar RAG): il chiamante deve poter osservare quando il suo intento non è stato rispettato.

Non distribuire codice di produzione con la modalità rigorosa attiva. Un parametro ignorato silenziosamente è un problema di esperienza per gli sviluppatori, non un guasto in fase di esecuzione, e un’eccezione in un percorso di rendering di produzione è peggiore dell’output degradato. Verificare, correggere e poi disattivarla — vedere /integrations/tcpdf-compat/migration/.

Costanti legacy TCPDF

TCPDF legacy legge la configurazione dalle costanti K_* e PDF_*. L’adattatore le definisce automaticamente durante la costruzione solo se non sono già definite, usando i valori predefiniti di TCPDF 6.2.13. Se l’applicazione definisce già una costante (per esempio una K_PATH_FONTS personalizzata), il valore già impostato viene preservato.

Valori predefiniti selezionati (elenco completo: src/Compat/Tcpdf/Config/LegacyDefaults.php):

Costante	Predefinito	Nota
`PDF_PAGE_FORMAT`	`A4`
`PDF_PAGE_ORIENTATION`	`P`
`PDF_UNIT`	`mm`
`PDF_MARGIN_LEFT` / `RIGHT`	`15`	unità utente
`PDF_MARGIN_TOP`	`27`	unità utente
`PDF_MARGIN_BOTTOM`	`25`	unità utente
`PDF_FONT_NAME_MAIN`	`helvetica`
`PDF_FONT_SIZE_MAIN`	`10`
`K_CELL_HEIGHT_RATIO`	`1.25`
`K_TCPDF_CALLS_IN_HTML`	`false`	rinforzata — sempre false; il markup non può attivare l’esecuzione di PHP
`K_TCPDF_THROW_EXCEPTION_ERROR`	`true`	rinforzata — `Error()` solleva sempre un’eccezione; mai `die()`
`K_TIMEZONE`	`UTC`

Due di queste costanti sono bloccate deliberatamente per ragioni di sicurezza e non possono essere allentate tramite configurazione: K_TCPDF_CALLS_IN_HTML è sempre false e K_TCPDF_THROW_EXCEPTION_ERROR è di fatto sempre true. Se il codice legacy dipende da uno di questi comportamenti legacy non sicuri, tale codice deve essere modificato — vedere /integrations/tcpdf-compat/security-and-operations/.

Definire eventuali costanti personalizzate prima della prima costruzione dell’adattatore (di norma nel bootstrap dell’applicazione):

<?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.

Il moderno oggetto AdaptationConfig

Per il codice che non vuole dipendere da costanti globali, il pacchetto fornisce un oggetto valore di configurazione immutabile, NextPDF\Compat\Tcpdf\Config\AdaptationConfig. È final readonly e ogni campo usa come valore predefinito quello di TCPDF 6.2.13. È possibile costruirlo in sicurezza con i soli campi che si desidera modificare.

È possibile costruirlo anche a partire dalle costanti legacy attualmente definite:

<?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 è il punto di arrivo della migrazione della configurazione. Man mano che i punti di chiamata passano alla moderna API, sostituire le letture di costanti con campi AdaptationConfig espliciti, in modo che la configurazione sia tipizzata e locale anziché globale.

Ordine di risoluzione della configurazione

Quando l’adattatore costruisce un documento, la configurazione viene risolta in questo ordine (i passaggi successivi non sovrascrivono quelli precedenti):

Argomenti del costruttore (orientation, unit, format, …) — precedenza più alta per i valori a cui si applicano.
Costanti legacy preesistenti definite dall’applicazione.
Costanti predefinite di TCPDF 6.2.13, definite automaticamente da LegacyDefaults per qualsiasi costante non già definita.

Gli argomenti del costruttore unicode, encoding e diskcache sono accettati per compatibilità della firma e non hanno alcun effetto. NextPDF è sempre Unicode e UTF-8 e non usa alcuna cache di pagina su disco. Anche il flag del costruttore pdfa è accettato, ma la conformità di archiviazione PDF/A richiede un’edizione commerciale (vedere /integrations/tcpdf-compat/security-and-operations/).

Vedere anche

src/Compat/Tcpdf/Config/LegacyDefaults.php — valori predefiniti autorevoli delle costanti
src/Compat/Tcpdf/Config/AdaptationConfig.php — moderno oggetto di configurazione
/integrations/tcpdf-compat/migration/ — spostare la configurazione al di fuori delle costanti globali
/integrations/tcpdf-compat/security-and-operations/ — i due flag rinforzati, non configurabili