Migrare via dalle librerie legacy: TCPDF, FPDF e affini

SpecSpec: ISO 32000-2ISO 32000-2SpecSpec: ISO 19005-4ISO 19005-4SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1

In sintesi

Se i PDF sono generati da TCPDF, FPDF, mPDF o dompdf, il codice probabilmente funziona ancora. È proprio per questo che il problema è facile da non notare. La libreria gira, il file si apre, e la lacuna emerge soltanto il giorno in cui qualcuno chiede un documento firmato, archiviabile o accessibile e la risposta è «da qui non possiamo».

Questa pagina è il racconto della migrazione: quali sono quei muri, perché sono strutturali e non incidentali, e in che modo NextPDF offre un percorso graduale per superarli — inclusa una superficie di compatibilità TCPDF che è un aiuto alla migrazione, non la promessa di un sostituto immediato e identico byte per byte.

Perché è importante

Una libreria PDF non è una chiamata di rendering che si effettua una volta sola. È una dipendenza che i documenti ereditano per tutto il tempo in cui esistono. Quando quella dipendenza smette di evolvere, i documenti smettono di poter fare cose nuove — e ce ne si accorge nel momento peggiore possibile, quando un cliente, un revisore o un’autorità di vigilanza alza l’asticella.

I muri si presentano così. Il formato è andato avanti: PDF 2.0 è l’edizione corrente dello standard (SpecSpec: ISO 32000-2ISO 32000-2), e un writer fermo sulla struttura 1.x è indietro rispetto al formato che il resto della toolchain presuppone. La firma è esile o aggiunta posticciamente, ben al di sotto dei profili baseline PAdES che fanno reggere una firma (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4). L’output archivistico verso la famiglia PDF/A, e la struttura etichettata per l’accessibilità, sono assenti oppure fragili. E la stessa API è non tipizzata — orientamenti come stringhe, booleani posizionali, valori predefiniti scoperti per caso — così il compilatore non può aiutare, e nemmeno un revisore può farlo.

Nessuna di queste è una bug aggirabile con una pezza. Sono la forma di uno strumento costruito per un decennio precedente, e diversi di quegli strumenti non si stanno più muovendo attivamente verso gli standard che i documenti ora devono soddisfare.

In breve

• Le librerie PDF PHP legacy per lo più funzionano ancora. Il problema è ciò che comunemente non riescono a produrre con piena conformità moderna: PDF 2.0, firme conformi al baseline, PDF/A validato, accessibilità etichettata — il supporto nelle librerie citate è limitato o assente.
• NextPDF è un motore PHP 8.4 che scrive PDF 2.0 per impostazione predefinita, con tipi rigorosi, profili archivistici e firma PAdES come output di prima classe.
• Non occorre riscrivere tutto dal primo giorno. La superficie di compatibilità TCPDF consente alle chiamate familiari di continuare a funzionare mentre si sposta la logica documentale che conta davvero.
• Quella superficie è compatibile con, non identica byte per byte a TCPDF. È un ponte attraverso la migrazione, con differenze comportamentali documentate — non l’affermazione che ogni script giri immutato.
• Il test onesto è se le nuove capacità valgono lo spostamento. Per alcuni carichi di lavoro non è così, e lo diciamo chiaramente.

Come NextPDF lo affronta

L’approccio è rendere la migrazione una sequenza, non un salto. Si continua a produrre documenti per tutto il percorso, e si abbandonano i vecchi vincoli uno alla volta anziché scommettere una release su una riscrittura big-bang.

1. InventarioCatalogare cosa i documenti hanno davvero bisogno di emettere — firme, profili archivistici, struttura etichettata, font — non solo quali chiamate si effettuano oggi.
2. PonteAdottare la superficie di compatibilità TCPDF così che le chiamate esistenti continuino a produrre file mentre il motore sottostante diventa NextPDF.
3. PortingSpostare la logica documentale che conta sull'API nativa tipizzata, dove l'intento è esplicito e il compilatore lo verifica.
4. UpgradeAttivare gli output che molte librerie legacy non riescono a raggiungere con piena conformità moderna: struttura PDF 2.0, PDF/A validato, firme PAdES, accessibilità etichettata.
5. VerificaConfermare il risultato rispetto a un validatore reale, così che «archivistico» o «firmato» significhi che uno strumento concorda, non solo che il file si è aperto.

Una migrazione graduale via da una libreria PDF legacy: si parte dalla superficie di compatibilità così che le chiamate esistenti continuino a funzionare, poi si sposta la logica documentale sull'API nativa tipizzata, poi si attivano gli output di livello standard (PDF 2.0, PDF/A, PAdES, accessibilità) che molte librerie legacy non riescono a produrre con piena conformità moderna.

PDF 2.0 è la base, non un feature flag. NextPDF scrive l’edizione corrente del formato per impostazione predefinita (SpecSpec: ISO 32000-2ISO 32000-2), e può serializzare strutture più datate quando un profilo le richiede. Una libreria congelata sulla struttura 1.x non può seguirti fin qui; non è un’impostazione che le manca, è un’epoca che precede.

Archiviazione e accessibilità sono proprietà del writer. Produrre un file che un validatore accetta come PDF/A è qualcosa che il motore deve fare mentre scrive — non può essere applicato a posteriori (SpecSpec: ISO 19005-4ISO 19005-4). Lo stesso vale per la struttura etichettata che rende un PDF accessibile. NextPDF costruisce questi elementi durante la generazione, che è esattamente il passo che molti strumenti legacy non riescono a compiere — o compiono solo parzialmente, al di sotto di ciò che un validatore accetta.

La firma supera l’asticella del baseline. Le firme elettroniche avanzate in un PDF seguono i profili PAdES (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4), dove il digest copre un intervallo di byte dichiarato e la firma porta con sé i metadati che un validatore verifica. Un helper di firma posticcio raramente raggiunge quell’asticella. NextPDF la tratta come un output di prima classe, non come un ripensamento.

La superficie di compatibilità è il ponte, dichiarato onestamente. Il livello di compatibilità TCPDF esiste perché le chiamate esistenti continuino a produrre documenti mentre si migrano le parti che contano. Segue lo stesso modello di ogni guida di migrazione NextPDF: compatibile con la libreria di origine, non identico byte per byte, con le differenze comportamentali messe per iscritto. Quell’onestà è il punto — una silenziosa affermazione di «99% drop-in» è proprio il tipo di ipotesi che questo motore è costruito per rifiutare.

Human-factors note:Human-factors note

Il motivo per migrare è raramente il codice che si ha oggi; è il documento che verrà chiesto domani. La manutenibilità è una proprietà di qualità definita — quanto prontamente un sistema può essere analizzato e modificato man mano che le esigenze cambiano (SpecSpec: ISO/IEC 25010, §3.6ISO/IEC 25010 §3.6). Una dipendenza che ha smesso di evolvere la erode silenziosamente, e se ne avverte il costo soltanto quando arriva un nuovo requisito e la risposta deve essere «da qui no». Uno spostamento graduale paga quel costo secondo i propri tempi, mentre i documenti continuano a fluire, anziché tutto in una volta sotto scadenza.

Esempio pratico

La forma di una migrazione è piccola al punto di chiamata. Il vecchio codice continua a produrre un file attraverso la superficie di compatibilità; il nuovo codice dichiara l’intento attraverso l’API nativa tipizzata e chiede un output che la libreria legacy non può raggiungere, o raggiunge solo con conformità limitata.

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use NextPDF\Contracts\Orientation;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

// 1) The bridge: a familiar TCPDF-shaped call keeps producing a file
//    while the engine underneath is already NextPDF. Behaviour is
//    compatible, not byte-identical — differences are documented.
$legacy = new TCPDF();
$legacy->AddPage();
$legacy->SetFont('helvetica', 'B', 16);
$legacy->Cell(0, 12, 'Migrated invoice', ln: 1);
$bridgedBytes = $legacy->Output('', 'S');

// 2) The destination: the same document expressed natively, where intent
//    is typed and the engine can emit what many legacy tools cannot.
$document = Document::createStandalone();
$document->setTitle('Migrated invoice');
$document->addPage(PageSize::a4(), Orientation::Portrait);
$document->setFont('helvetica', 'B', 16);
$document->cell(0, 12, 'Migrated invoice', newLine: true);

// Bytes only, no HTTP headers, no file side effect — stated, not inferred.
$nativeBytes = $document->output(dest: OutputDestination::String);

Il primo blocco è l’appiglio: nulla nell’applicazione deve cambiare perché i documenti continuino a fluire. Il secondo è la destinazione: una chiamata tipizzata dove «verticale», «output come stringa» e il font sono espliciti, e dove archiviazione, firma e accessibilità diventano output che si possono attivare anziché muri contro cui ci si scontra.

Equivoco comune

La speranza ricorrente è «ci sarà pure un flag che fa fare PDF 2.0 e firme alla mia vecchia libreria». Non c’è. Non sono opzioni che una libreria matura si è dimenticata di esporre; sono capacità attorno a cui la sua architettura non è mai stata costruita. Non si può arrivare per configurazione a un’edizione di formato o a un profilo di firma che un writer non implementa.

L’equivoco speculare è che NextPDF sia un sostituto drop-in al 100% di TCPDF, e che quindi la migrazione sia gratis. Non lo è, e non fingeremo il contrario. La superficie di compatibilità copre una porzione reale e documentata dell’API per accompagnarti attraverso lo spostamento; alcune chiamate si comportano in modo diverso, e alcune sono fuori dall’ambito. Va trattata come un ponte con una mappa pubblicata, non come una garanzia che ogni script legacy giri immutato.

Limiti e confini

TCPDF-compatibility surface as a migration aid — edition availability

Edition	Availability
Core	○ La superficie di compatibilità è compatibile con, non identica byte per byte a TCPDF. Copre un sottoinsieme documentato dell’API per mantenere le chiamate esistenti in grado di produrre file durante la migrazione. È un ponte, non un drop-in: alcuni comportamenti differiscono e alcune chiamate non sono supportate, tutto elencato nelle pagine di copertura dei metodi e di migrazione. La destinazione è l’API nativa tipizzata, dove vive l’output di livello standard.
Pro	●Available
Enterprise	●Available

La migrazione è un mezzo, non una virtù. Se i documenti sono semplici, la libreria è ancora mantenuta, e non serviranno mai PDF 2.0, firma, PDF/A o accessibilità, la risposta onesta potrebbe essere restare dove si è — il costo di passaggio è reale e uno spostamento di cui non si ha bisogno è uno spostamento che non si dovrebbe fare. La pagina su quando non usare NextPDF traccia quella linea senza esitazioni.

Questa pagina descrive il percorso di migrazione e gli obiettivi del motore. La copertura esatta dell’API, le differenze comportamentali e la procedura passo passo vivono nella documentazione di compatibilità, che è l’autorità su cosa fa ciascuna chiamata. Nulla qui promette che uno script legacy arbitrario giri immutato.

Documentazione correlata

• What PDF 2.0 changed — l’edizione di formato che molte librerie legacy non riescono a emettere, e perché è importante.
• The TCPDF compatibility surface — la guida autorevole su cosa copre il ponte e dove differisce.
• When not to use NextPDF — il confine onesto, perché una migrazione di cui non si ha bisogno è una che si può saltare.
• One engine, every framework — dove il motore verso cui si migra si innesta nello stack già in uso.

Glossario

• PDF 2.0 — l’edizione corrente dello standard Portable Document Format (ISO 32000-2). Esplicitato al primo utilizzo; il formato che NextPDF scrive per impostazione predefinita.
• PDF/A — la famiglia di conformità archivistica (la serie ISO 19005) che definisce ciò che rende un PDF sicuro da preservare nel lungo termine. Una proprietà che il writer deve produrre, non una che un chiamante possa aggiungere in seguito.
• PAdES — PDF Advanced Electronic Signatures, la famiglia di profili ETSI (EN 319 142) per incorporare firme di livello standard in un PDF. Esplicitato al primo utilizzo; trattato in profondità nelle pagine sulla firma.
• Superficie di compatibilità — un livello di API modellato come una libreria di origine (qui, TCPDF) che consente alle chiamate esistenti di continuare a funzionare durante la migrazione. Compatibile con, non identica byte per byte a, l’originale — un ponte, non un drop-in.
• Sostituto drop-in — un rimpiazzo che esegue il codice esistente immutato. La superficie di compatibilità TCPDF è deliberatamente non descritta in questo modo; è un aiuto alla migrazione documentato, con differenze comportamentali note.