Migreren van TCPDF 6.x naar NextPDF

In een oogopslag

Migreer stapsgewijs. Stap eerst met de kleinst mogelijke wijziging over naar de NextPDF-engine. Toon aan wat al werkt. Breng in kaart wat niet werkt. Repareer elke aanroepplek. Verwijder daarna de adapter. De compatibiliteitslaag ondersteunt stap twee tot en met vier; ze is niet de eindbestemming.

Deze pagina geeft u de migratiestrategie. Raadpleeg voor het exacte gedrag van een afzonderlijke methode /integrations/tcpdf-compat/method-coverage/ samen met de gezaghebbende matrix in de repository, docs/TCPDF_COVERAGE.md.

Migratiemodel

Diagram

Elke fase houdt de applicatie leverbaar. U hoeft de omschakeling nooit in één keer te doen.

Fase 1 — Wissel de dependency

Installeer nextpdf/compat-legacy (zie /integrations/tcpdf-compat/install/). Verwijder tecnickcom/tcpdf nog niet; door beide te behouden, kunt u resultaten vergelijken.

Kies hoe verouderde aanroepplekken de class resolveren:

• Aanbevolen: wijzig in elk bestand de use/require naar use NextPDF\Compat\Tcpdf\TCPDF;. Dit is expliciet en eenvoudig te doorzoeken.
• Wanneer u de aanroepplekken nog niet kunt aanpassen: schakel bij het opstarten eenmalig globale opt-in-aliassen in met LegacyBootstrap::enableAliases() (zie /integrations/tcpdf-compat/boot-and-discovery/). Hierdoor resolveren \TCPDF en de vier helperclasses naar de adapter.

De twee strategieën sluiten elkaar in de praktijk uit. Als de echte TCPDF-bibliotheek autoloadbaar blijft en u globale aliassen inschakelt, wordt de alias overgeslagen wanneer er al een \TCPDF-class bestaat. U kunt dan ongemerkt de verouderde TCPDF blijven gebruiken. Geef in fase 1 de voorkeur aan imports per bestand, zodat u precies weet welke class elke aanroepplek gebruikt. Zie /integrations/tcpdf-compat/troubleshooting/.

Fase 2 — Voer de bestaande suite ongewijzigd uit

Voer uw volledige testsuite uit tegen de adapter zonder verder iets te wijzigen. De meeste gedelegeerde methoden (94 van de ~120 onderzochte) gedragen zich compatibel. Verwacht twee voorspelbare categorieën mislukkingen:

1. Assertions op byteniveau. Tests die exacte Portable Document Format (PDF)-bytes vergelijken, zullen mislukken omdat de engine een onafhankelijke implementatie is. Dit is te verwachten en geen defect. Stel deze uit tot fase 4.
2. Vertakkingen op retourwaarden. Een paar methoden retourneren compatibiliteitsplaceholders in plaats van berekende waarden. Het opvallendst zijn MultiCell(), dat 1 retourneert, en Write(), dat 0 retourneert. Code die vertakt op die retourwaarden, moet worden aangepast.

Catalogiseer elke mislukking. Classificeer die als byte-baseline, retourwaarde of echte gedragskloof.

Fase 3 — Audit in strikte modus

Deze fase maakt de migratie veilig. Voer de suite of een representatief productiepad uit met de strikte modus ingeschakeld:

examples/migration-audit.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

function renderInvoice(TCPDF $pdf): void
{
    // ... your existing rendering code, unchanged ...
}

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->setStrictMode(true);

try {
    renderInvoice($pdf);
    $pdf->Output(__DIR__ . '/audit.pdf', 'F');
} catch (TcpdfNotImplementedException $e) {
    // Each message names the method, the ignored parameters, and a hint.
    fwrite(STDERR, 'MIGRATION GAP: ' . $e->getMessage() . "\n");
}

Behandel elke TcpdfNotImplementedException als één taak. Het bericht geeft u de methode, de exacte lijst met genegeerde parameters en een migratiehint. De verzameling methoden die een exception werpen, staat opgesomd en is met tests vastgelegd in tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php. De onderbouwing per methode staat in docs/TCPDF_COVERAGE.md.

Gebruik de strikte modus als een specifieke continuous integration (CI)-taak, niet in productie. Het doel is om kloven aan het licht te brengen, niet om in productie een exception te laten werpen.

Fase 4 — Repareer aanroepplekken

Kies voor elke kloof de goedkoopste correcte oplossing:

Kloofpatroon	Oplossing
Genegeerde parameter doet er niet toe (e.g. een TCPDF-$align waarop u nooit hebt vertrouwd)	Laat de parameter weg. De aanroep wordt exact compatibel.
Genegeerde parameter deed er wel toe (e.g. een aanklikbare Image()-link)	Druk dit opnieuw uit met de moderne API. Teken de afbeelding en voeg vervolgens Document::link() over de rechthoek toe.
Methode is niet geïmplementeerd (setSignature(), endPage())	endPage() / Open(): verwijder de aanroep. Voor ondertekenen: zie /integrations/tcpdf-compat/security-and-operations/; hiervoor is een commerciële editie vereist.
Niet-toepasselijke methode (setPDFVersion(), setUserRights())	Verwijder de aanroep. De uitvoer is altijd PDF 2.0; user-rights is verouderd in PDF 2.0.
Vertakking op retourwaarde	Bereken de waarde zelf, of verplaats die logica naar de moderne API.

Gebruik de escape hatch wanneer het TCPDF-oppervlak niet kan uitdrukken wat u nodig hebt:

examples/migration-escape-hatch.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();

// Legacy path stays as-is for the parts that work:
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Header line', 0, 1);

// Modern path for what the TCPDF surface cannot express here:
$document = $pdf->getDocument();
$document->image('logo.png', 10, 30, 40, 0);
$document->link(10, 30, 40, 20, 'https://example.com');

Stel byteniveau-tests opnieuw in als baseline

Vervang assertions op exacte bytes door assertions over wat ertoe doet:

• De uitvoer begint met %PDF en wordt geparseerd (op smoke-niveau).
• Weergegeven tekstinhoud is aanwezig (extraheer de tekst en stel daar assertions op).
• Structurele eigenschappen (aantal pagina’s, paginaformaat en aanwezigheid van een outline) komen overeen.

Deze eenmalige investering levert u tests op die toekomstige upgrades van de engine overleven.

Fase 5 — Verwijder de TCPDF-dependency

Nadat de audit in strikte modus is geslaagd, de strikte modus in productie uit staat en de suite groen is met de opnieuw ingestelde baseline-assertions, verwijdert u tecnickcom/tcpdf:

composer remove tecnickcom/tcpdf

Voer de suite opnieuw uit. Als er nog iets naar de echte TCPDF-class verwijst, was de aliaswaarschuwing van fase 1 van toepassing; pas de resterende aanroepplekken aan, zodat ze de adapter expliciet importeren.

Fase 6 — Faseer de adapter uit

De adapter is een migratiehulpmiddel, geen permanente laag. Nadat TCPDF is verdwenen en de engine zich heeft bewezen, faseert u de adapter stapsgewijs uit:

1. Vervang in elke module new TCPDF(...) door de moderne NextPDF\Core\Document-constructie.
2. Vervang TCPDF-methodeaanroepen door hun moderne equivalenten (de getDocument()-aanroepen die u al in fase 4 hebt toegevoegd, dienen als sjabloon).
3. Zodra een module niet langer naar de adapter verwijst, verwijdert u de bijbehorende compatibiliteitsimports.
4. Zodra geen enkele module naar de adapter verwijst, verwijdert u nextpdf/compat-legacy uit composer.json.

Op dat moment werkt u met de moderne PDF 2.0-API zonder compatibiliteitslaag.

Migratiechecklist

• nextpdf/compat-legacy geïnstalleerd; enginekoppeling geverifieerd.
• Aanroepplekken importeren de adapter expliciet (of aliassen zijn ingeschakeld nadat de echte TCPDF uit het autoloadpad is verwijderd).
• Volledige suite uitgevoerd tegen de adapter; mislukkingen geclassificeerd.
• CI-taak in strikte modus toegevoegd; elke kloof gecatalogiseerd.
• Elke kloof gerepareerd (parameter weglaten / moderne API / aanroep verwijderen).
• Assertions op byteniveau opnieuw als baseline ingesteld op inhoud en structuur.
• tecnickcom/tcpdf verwijderd; suite groen.
• Adapter module voor module uitgefaseerd; dependency verwijderd.

Zie ook

• /integrations/tcpdf-compat/method-coverage/ — gedrag per methode en richtlijnen voor vervanging
• docs/TCPDF_COVERAGE.md — gezaghebbende, met tests geverifieerde matrix
• /integrations/tcpdf-compat/configuration/ — configuratie loskoppelen van globale constanten
• /integrations/tcpdf-compat/security-and-operations/ — versleuteling en ondertekening tijdens de migratie
• /integrations/tcpdf-compat/troubleshooting/ — het alias/real-TCPDF-conflict en andere valkuilen