Migreren van legacy: TCPDF, FPDF en consorten

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

In een oogopslag

Als je PDF’s worden gegenereerd door TCPDF, FPDF, mPDF of dompdf, werkt de code waarschijnlijk nog steeds. Juist daarom is het probleem makkelijk over het hoofd te zien. De bibliotheek draait, het bestand opent, en de kloof komt pas aan het licht op de dag dat iemand om een ondertekend, archiveerbaar of toegankelijk document vraagt en het antwoord is “dat kunnen we van hieruit niet.”

Deze pagina is het migratieverhaal: wat die muren zijn, waarom ze structureel zijn in plaats van toevallig, en hoe NextPDF je een gefaseerd pad eraf biedt — inclusief een TCPDF-compatibiliteitsoppervlak dat een migratiehulp is, geen belofte van een byte-identieke drop-in.

Waarom dit ertoe doet

Een PDF-bibliotheek is geen render-aanroep die je één keer doet. Het is een afhankelijkheid die je documenten erven zolang ze bestaan. Wanneer die afhankelijkheid stopt met bewegen, verliezen je documenten het vermogen om nieuwe dingen te doen — en je komt daar op het slechtst denkbare moment achter, wanneer een klant, een auditor of een toezichthouder de lat legt.

De muren zien er zo uit. Het formaat ging verder: PDF 2.0 is de huidige editie van de standaard (SpecSpec: ISO 32000-2ISO 32000-2), en een writer die vastzit op de 1.x-structuur loopt achter op het formaat dat de rest van je toolchain veronderstelt. Ondertekenen is mager of erbovenop geplakt, ver onder de PAdES-baseline-profielen die een handtekening laten standhouden (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4). Archiveeruitvoer naar de PDF/A-familie, en getagde structuur voor toegankelijkheid, zijn ofwel afwezig ofwel fragiel. En de API zelf is ongetypeerd — string- oriëntaties, positionele booleans, defaults die je per ongeluk ontdekt — zodat de compiler je niet kan helpen en een reviewer evenmin.

Geen van deze zijn bugs waar je omheen kunt patchen. Ze zijn de vorm van een tool gebouwd voor een eerder decennium, en verschillende van die tools bewegen niet langer actief in de richting van de standaarden waaraan je documenten nu moeten voldoen.

De korte versie

• Legacy PHP-PDF-bibliotheken draaien meestal nog steeds. Het probleem is wat ze doorgaans niet met volledige moderne conformiteit kunnen produceren: PDF 2.0, baseline-conforme handtekeningen, gevalideerde PDF/A, getagde toegankelijkheid — ondersteuning over de genoemde bibliotheken heen is beperkt of afwezig.
• NextPDF is een PHP 8.4-engine die standaard PDF 2.0 schrijft, met strikte types, archiveerprofielen en PAdES-ondertekening als eersteklas uitvoer.
• Je hoeft niet op dag één alles te herschrijven. Het TCPDF-compatibiliteits- oppervlak laat vertrouwde aanroepen blijven werken terwijl je de documentlogica verplaatst die ertoe doet.
• Dat oppervlak is compatibel met, niet byte-identiek aan TCPDF. Het is een brug over de migratie heen, met gedocumenteerde gedragsverschillen — geen claim dat elk script ongewijzigd draait.
• De eerlijke toets is of de nieuwe mogelijkheden de overstap waard zijn. Voor sommige werklasten zijn ze dat niet, en dat zeggen we ronduit.

Hoe NextPDF dit aanpakt

De aanpak is om migratie een opeenvolging te maken, geen sprong. Je blijft de hele weg documenten produceren, en je ruilt oude beperkingen één voor één in in plaats van een release op een big-bang-herschrijving te zetten.

1. InventoryCatalogue what your documents actually need to emit — signatures, archival profiles, tagged structure, fonts — not just which calls you make today.
2. BridgeAdopt the TCPDF-compatibility surface so the existing call sites keep producing files while the engine underneath becomes NextPDF.
3. PortMove the document logic that matters onto the native typed API, where intent is explicit and the compiler checks it.
4. UpgradeTurn on the outputs many legacy libraries cannot reach with full modern conformance: PDF 2.0 structure, validated PDF/A, PAdES signatures, tagged accessibility.
5. VerifyConfirm the result against a real validator, so 'archival' or 'signed' means a tool agrees, not just that the file opened.

Een gefaseerde migratie van een legacy PDF-bibliotheek: begin op het compatibiliteitsoppervlak zodat bestaande aanroepen blijven werken, verplaats vervolgens documentlogica naar de getypeerde native API, en zet daarna de standaardvaste uitvoer aan (PDF 2.0, PDF/A, PAdES, toegankelijkheid) die veel legacy-bibliotheken niet met volledige moderne conformiteit kunnen produceren.

PDF 2.0 is de baseline, geen feature flag. NextPDF schrijft de huidige editie van het formaat standaard (SpecSpec: ISO 32000-2ISO 32000-2), en kan oudere structuren serialiseren wanneer een profiel daarom vraagt. Een bibliotheek bevroren op de 1.x-structuur kan je hier niet tegemoetkomen; het is geen instelling die ze mist, het is een tijdperk dat ze voorafgaat.

Archivering en toegankelijkheid zijn writer-eigenschappen. Een bestand produceren dat een validator als PDF/A accepteert, is iets wat de engine al schrijvend moet doen — het kan er achteraf niet op worden geniet (SpecSpec: ISO 19005-4ISO 19005-4). Hetzelfde geldt voor de getagde structuur die een PDF toegankelijk maakt. NextPDF bouwt deze tijdens de generatie op, wat precies de stap is die veel legacy-tools niet kunnen zetten — of slechts gedeeltelijk zetten, onder wat een validator accepteert.

Ondertekenen haalt de baseline-lat. Geavanceerde elektronische handtekeningen in een PDF volgen de PAdES-profielen (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4), waarbij de digest een opgegeven bytebereik dekt en de handtekening de metadata draagt die een validator controleert. Een erop geplakte ondertekeningshelper haalt die lat zelden. NextPDF behandelt het als eersteklas uitvoer, geen bijzaak.

Het compatibiliteitsoppervlak is de brug, eerlijk gesteld. De TCPDF-compat- laag bestaat zodat je bestaande aanroeplocaties documenten blijven produceren terwijl je de delen die ertoe doen migreert. Hij volgt hetzelfde model als elke NextPDF- migratiegids: compatibel met de bronbibliotheek, niet byte-identiek, met de gedragsverschillen opgeschreven. Die eerlijkheid is het punt — een stille “99% drop-in”-claim is precies het soort gok dat deze engine gebouwd is om te weigeren.

Human-factors note:Human-factors note

De reden om te migreren is zelden de code die je vandaag hebt; het is het document dat je morgen gevraagd wordt. Onderhoudbaarheid is een benoemde kwaliteitseigenschap — hoe bereidwillig een systeem kan worden geanalyseerd en gewijzigd naarmate behoeften verschuiven (SpecSpec: ISO/IEC 25010, §3.6ISO/IEC 25010 §3.6). Een afhankelijkheid die is gestopt met bewegen erodeert die stilletjes, en je voelt de kosten pas wanneer een nieuwe eis arriveert en het antwoord “niet van hieruit” moet zijn. Een gefaseerde overstap betaalt die kosten op jouw schema, terwijl de documenten blijven stromen, in plaats van allemaal tegelijk onder deadline.

Praktijkvoorbeeld

De vorm van een migratie is klein op de aanroeplocatie. Oude code blijft een bestand produceren via het compatibiliteitsoppervlak; nieuwe code stelt de intentie via de getypeerde native API en vraagt om een uitvoer die de legacy-bibliotheek niet kan bereiken, of slechts met beperkte conformiteit bereikt.

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

Het eerste blok is het houvast: niets in je applicatie hoeft te veranderen opdat documenten blijven stromen. Het tweede is de bestemming: een getypeerde aanroep waarbij “portrait”, “string-uitvoer” en het lettertype expliciet zijn, en waar archivering, ondertekening en toegankelijkheid uitvoer worden die je kunt aanzetten in plaats van muren waar je tegenaan loopt.

Veelvoorkomend misverstand

De veelvoorkomende hoop is “er moet wel een flag zijn die mijn oude bibliotheek PDF 2.0 en handtekeningen laat doen.” Die is er niet. Dit zijn geen opties die een volwassen bibliotheek vergat bloot te leggen; het zijn mogelijkheden waar haar architectuur nooit omheen is gebouwd. Je kunt je niet een weg configureren naar een formaateditie of een handtekeningprofiel dat een writer niet implementeert.

Het spiegelbeeldige misverstand is dat NextPDF een 100% TCPDF-drop-in is, zodat migratie gratis is. Dat is het niet, en we zullen niet doen alsof het anders is. Het compatibiliteitsoppervlak dekt een reële, gedocumenteerde plak van de API om je over de overstap heen te dragen; sommige aanroepen gedragen zich anders, en een paar vallen buiten de scope. Behandel het als een brug met een gepubliceerde kaart, geen garantie dat elk legacy- script onaangeroerd draait.

Limieten en grenzen

TCPDF-compatibility surface as a migration aid — edition availability

Edition	Availability
Core	○ Het compatibiliteitsoppervlak is compatibel met, niet byte-identiek aan TCPDF. Het dekt een gedocumenteerde subset van de API om bestaande aanroeplocaties bestanden te laten produceren tijdens de migratie. Het is een brug, geen drop-in: sommige gedragingen verschillen en sommige aanroepen worden niet ondersteund, alle vermeld in de methodedekking- en migratiepagina’s. De bestemming is de native getypeerde API, waar standaardvaste uitvoer thuishoort.
Pro	●Available
Enterprise	●Available

Migratie is een middel, geen deugd. Als je documenten eenvoudig zijn, je bibliotheek nog steeds wordt onderhouden, en je nooit PDF 2.0, ondertekenen, PDF/A of toegankelijkheid nodig hebt, kan het eerlijke antwoord zijn om te blijven waar je bent — overstapkosten zijn reëel en een overstap die je niet nodig hebt is een overstap die je niet zou moeten maken. De pagina over wanneer NextPDF niet te gebruiken trekt die lijn zonder met de ogen te knipperen.

Deze pagina beschrijft het migratiepad en de doelen van de engine. De exacte API-dekking, de gedragsverschillen en de stapsgewijze procedure staan in de compatibiliteitsdocumentatie, die de autoriteit is voor wat elke aanroep doet. Niets hier belooft dat een willekeurig legacy-script ongewijzigd draait.

Verwante documentatie

• Wat PDF 2.0 veranderde — de formaat- editie die veel legacy-bibliotheken niet kunnen uitsturen, en waarom dat ertoe doet.
• Het TCPDF-compatibiliteitsoppervlak — de gezaghebbende gids voor wat de brug dekt en waar hij afwijkt.
• Wanneer NextPDF niet te gebruiken — de eerlijke grens, zodat een migratie die je niet nodig hebt er een is die je kunt overslaan.
• Eén engine, elk framework — waar de engine waarnaar je migreert inprikt op de stack die je al draait.

Verklarende woordenlijst

• PDF 2.0 — de huidige editie van de Portable Document Format-standaard (ISO 32000-2). Bij eerste gebruik uitgeschreven; het formaat dat NextPDF standaard schrijft.
• PDF/A — de archiveerconformiteitsfamilie (de ISO 19005-serie) die definieert wat een PDF veilig maakt om langdurig te bewaren. Een eigenschap die de writer moet produceren, niet een die een aanroeper later kan toevoegen.
• PAdES — PDF Advanced Electronic Signatures, de ETSI-profielfamilie (EN 319 142) voor het inbedden van standaardvaste handtekeningen in een PDF. Bij eerste gebruik uitgeschreven; uitgebreid behandeld op de ondertekeningspagina’s.
• Compatibiliteitsoppervlak — een API-laag gevormd als een bronbibliotheek (hier, TCPDF) die bestaande aanroeplocaties laat blijven werken tijdens de migratie. Compatibel met, niet byte-identiek aan, het origineel — een brug, geen drop-in.
• Drop-in-vervanging — een vervanging die bestaande code ongewijzigd draait. Het TCPDF-compat-oppervlak wordt bewust niet zo beschreven; het is een gedocumenteerde migratiehulp met bekende gedragsverschillen.