Avvio rapido di compat-legacy

In sintesi

Questa pagina accompagna dal pacchetto installato a un PDF completo, quindi all’audit in modalità strict da eseguire prima della migrazione. Ogni blocco di codice rispecchia un comportamento verificato dalla suite di test del pacchetto, quindi l’output mostrato qui coincide con ciò che i test controllano.

Prima di iniziare

Installare il pacchetto e confermare il collegamento al motore seguendo /integrations/tcpdf-compat/install/. È necessario PHP 8.4 e nextpdf/core ^3.0 deve essere risolto correttamente.

1. Generare il primo documento

Modificare l’import e mantenere le chiamate in stile TCPDF. Questa è esattamente la superficie verificata da tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetCreator('Quickstart');
$pdf->SetTitle('First Document');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

Eseguirlo:

php examples/quickstart-first.php

Il file quickstart.pdf è un PDF 2.0 valido. La suite di test verifica che l’output equivalente come stringa inizi con %PDF per le destinazioni S, F ed E e per getPDFData().

Destinazioni di output

Output($name, $dest) mappa i codici di destinazione di TCPDF tramite un ponte di output sicuro. Questo è il comportamento esercitato dalla suite di test:

`$dest`	Comportamento	Restituisce
`'S'`	Restituisce il PDF come stringa	i byte del PDF (`%PDF…`)
`'F'`	Scrive il PDF nel percorso indicato	stringa vuota
`'E'`	Restituisce un corpo MIME in base64	un blocco con `Content-Type: application/pdf`
`'I'`	Inline (predefinito)	in base al ponte di output
`'D'`	Download	in base al ponte di output

A differenza del TCPDF legacy, Output() non scrive direttamente nel buffer di output attivo, quindi è possibile richiamarlo in sicurezza all’interno di un worker di coda o di un handler HTTP che controlla la risposta. Vedere /integrations/tcpdf-compat/production-usage/.

2. Eseguire codice TCPDF esistente senza modifiche

In una migrazione reale, eseguire prima di tutto il codice esistente modificando solo l’import o l’alias. Se la base di codice richiama new \TCPDF(...) nel namespace globale, abilitare gli alias opzionali una sola volta all’avvio (trattati in /integrations/tcpdf-compat/boot-and-discovery/):

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Legacy code now resolves \TCPDF to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/aliased.pdf', 'F');

LegacyBootstrap::enableAliases() è idempotente. Registra \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS e \TCPDF_IMAGES solo se tali classi non esistono già. Il test del pacchetto tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php verifica che gli alias vengano registrati, che la chiamata sia idempotente e che new \TCPDF() sia un’istanza dell’adattatore. Non abilitare gli alias se la libreria TCPDF reale è caricata nello stesso processo: vedere /integrations/tcpdf-compat/troubleshooting/.

3. Eseguire l’audit con la modalità strict

È questo passaggio a rendere sicura una migrazione. Con la modalità strict disattivata (impostazione predefinita), i metodi che non riescono a riprodurre il comportamento di TCPDF ripiegano in modo silenzioso. Con la modalità strict attivata, sollevano TcpdfNotImplementedException con l’elenco esatto dei parametri ignorati. Eseguire questo controllo in una passata di audit dedicata, mai in produzione.

<?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 {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

Il test del pacchetto tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php verifica che questa esatta chiamata sollevi un’eccezione in modalità strict e resti silenziosa in modalità predefinita, e che il messaggio contenga il nome del metodo e i parametri ignorati. Usare le eccezioni raccolte come elenco di attività per la migrazione: vedere /integrations/tcpdf-compat/migration/.

4. Accedere all’API moderna quando serve

Ogni istanza dell’adattatore espone il documento del motore sottostante. Usarlo per richiamare i metodi moderni di NextPDF che non hanno un equivalente TCPDF:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument() restituisce il NextPDF\Core\Document incapsulato dall’adattatore. Questo è il percorso di uscita consigliato: migrare i punti di chiamata verso l’API moderna uno alla volta, finché non sarà possibile rimuovere l’adattatore.

Differenze di comportamento da aspettarsi subito

MultiCell() restituisce 1, non il numero di celle rese. Il codice che sceglie il flusso in base al valore restituito da MultiCell() richiede un adeguamento.
Error() solleva RuntimeException invece di chiamare die(). Il codice che si basava sulla terminazione del processo deve intercettare l’eccezione.
I byte esatti del PDF differiscono dall’output di TCPDF. Aggiornare la baseline delle asserzioni di test a livello di byte, in modo che verifichino invece il contenuto reso.

L’elenco completo, metodo per metodo, è in /integrations/tcpdf-compat/method-coverage/.

Passi successivi

/integrations/tcpdf-compat/migration/ — la strategia di migrazione completa, file per file.
/integrations/tcpdf-compat/configuration/ — la modalità strict, i valori predefiniti e l’oggetto di configurazione moderno.
/integrations/tcpdf-compat/production-usage/ — i worker, i buffer di output e le prestazioni.
/integrations/tcpdf-compat/security-and-operations/ — le impostazioni di cifratura e firma.

Vedere anche

tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — oracolo per il comportamento di output
tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — oracolo per la modalità strict
docs/TCPDF_COVERAGE.md — matrice di copertura autorevole