TCPDF-methodedekking voor NextPDF compat-legacy

In één oogopslag

nextpdf/compat-legacy is een compatibiliteitslaag, geen fork van TCPDF en geen gegarandeerde gedragskloon. De laag stelt de publieke methodenamen, parametervolgorde en standaardwaarden van TCPDF 6.x beschikbaar bovenop de NextPDF-kernengine. De meeste aanroepen worden rechtstreeks toegewezen aan een NextPDF-Document-bewerking. Een duidelijk afgebakend kleiner deel accepteert verouderde parameters die NextPDF niet honoreert of die geen effect hebben.

Deze pagina vat de audit per methode samen. De gezaghebbende, met tests geverifieerde dekkingsmatrix bevindt zich in de repository onder docs/TCPDF_COVERAGE.md. Als deze pagina en de matrix in de repository van elkaar verschillen, is de matrix in de repository bepalend, omdat de testsuite die afdwingt.

Gebruik deze pagina om vóór de migratie één vraag te beantwoorden: voor elke TCPDF-methode die mijn codebase aanroept, wat doet de adapter precies?

Dekkingsoverzicht

De audit onderzocht ongeveer 120 publieke TCPDF 6.x-methoden. Elke methode is in precies één van vier categorieën geplaatst.

Categorie	Aantal	Wat dit betekent
Gespiegeld — volledig gedelegeerd	94	De aanroep wordt rechtstreeks toegewezen aan een NextPDF-`Document`-methode. Het gedrag is compatibel voor de gedocumenteerde parameters.
Stil genegeerd — gedeeltelijk	15	De methode draait en produceert uitvoer, maar een of meer TCPDF-parameters hebben geen effect. Dit is een gedocumenteerd gedragsverschil.
Niet geïmplementeerd — lege body	4	De methode bestaat voor broncompatibiliteit, maar doet niets.
Niet van toepassing	7	De TCPDF-methode heeft geen effect op de PDF-uitvoer; opzettelijk uitgesloten.
Toegevoegde methoden door moderne-API-drift	17	NextPDF v5.1+-Document-methoden die op de adapter beschikbaar zijn gesteld, zodat code met een gemengde API compileert. Deze hebben geen TCPDF 6.x-equivalent.

Deze cijfers komen uit docs/TCPDF_COVERAGE.md §Summary. De testsuite verifieert de matrix via tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php en tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php.

Opmerking over de formulering. Dit pakket beweert niet dat het een „drop-in replacement” of „100% TCPDF-compatibel” is. Het dekt 94 van de onderzochte ~120 TCPDF-methoden via directe delegatie. De overige methoden hebben gedocumenteerde gedragsverschillen, die hieronder worden beschreven. De juiste beschrijving is TCPDF-compatibel alternatief met een bekend, getest compatibiliteitsoppervlak.

Een opmerking over de methodetellingen

De adapter is opgebouwd uit 25 concern-traits met één verantwoordelijkheid (src/Compat/Tcpdf/Concerns/) die in totaal 273 publieke methoden beschikbaar stellen, plus een klein aantal levenscyclus- en escape-hatch-methoden op de TCPDF-klasse zelf. De dekkingscategorieën hierboven tellen afzonderlijke methoden van het TCPDF 6.x-API-oppervlak (~120), niet het totale aantal publieke methoden van de adapter. De twee getallen meten verschillende dingen: dekking van het API-oppervlak en omvang van de implementatie. Als de README.md van het pakket een kleiner aantal traits of methoden noemt, beschouw dan docs/TCPDF_COVERAGE.md en deze pagina als gezaghebbend. De README-samenvatting dateert van vóór de AdaptsDriftV51-trait.

1. Gespiegelde methoden — compatibele delegatie

Vierennegentig methoden worden rechtstreeks toegewezen aan de onderliggende NextPDF\Core\Document-instantie. PascalCase-TCPDF-namen worden toegewezen aan camelCase-NextPDF-namen waar de engine camelCase gebruikt. De adapter accepteert beide schrijfwijzen voor voorwaartse en achterwaartse compatibiliteit.

Representatieve groepen (volledige tabel: docs/TCPDF_COVERAGE.md §1):

TCPDF-gebied	Voorbeeldmethoden	Adapter-trait
Levenscyclus	`Output()`, `Close()`, `getPDFData()`	`AdaptsLifecycle`
Pagina’s	`AddPage()`, `getNumPages()`, `deletePage()`	`AdaptsPageManagement`
Tekst	`Cell()`, `MultiCell()`, `Write()`, `Text()`, `Ln()`	`AdaptsTextOutput`
Lettertypen	`SetFont()`, `SetFontSize()`, `AddFont()`	`AdaptsFonts`
Kleuren	`SetTextColor()`, `SetDrawColor()`, `SetFillColor()`	`AdaptsColors`
Tekenen	`Line()`, `Rect()`, `Circle()`, `Polygon()`, `Arrow()`	`AdaptsDrawing`
Transformaties	`Rotate()`, `Scale()`, `Translate()`, `Skew()`, `Mirror*()`	`AdaptsTransforms`
Navigatie	`AddLink()`, `Annotation()`, `addTOC()`	`AdaptsNavigation`

Voor deze methoden is het waargenomen gedrag compatibel met TCPDF 6.x voor de parameters die NextPDF documenteert. De adapter garandeert geen byte-identieke PDF-uitvoer. De onderliggende engine is een onafhankelijke PDF 2.0-implementatie, dus de bytes kunnen verschillen, zelfs als het zichtbare resultaat gelijkwaardig is. Als uw tests exacte PDF-bytes controleren in plaats van gerenderde inhoud, houd er dan rekening mee dat u die asserties opnieuw als baseline moet vaststellen. Zie /integrations/tcpdf-compat/migration/ voor de aanbevolen rebaseline-strategie.

2. Stil genegeerde methoden — gedocumenteerde gedragsverschillen

Deze 15 methoden worden uitgevoerd en produceren uitvoer, maar ten minste één TCPDF-parameter wordt voor broncompatibiliteit geaccepteerd en daarna genegeerd. Lees dit gedeelte voordat u migreert. Deze aanroepen mislukken niet; ze doen stilzwijgend minder dan het TCPDF-origineel.

TCPDF-methode	Genegeerde parameters	Compatibel alternatief
`Image()`	type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs	NextPDF `image()` neemt file, x, y, width, height. Teken voor een klikbare afbeelding eerst de afbeelding en voeg vervolgens `Document::link()` over dezelfde rechthoek toe. Afbeeldingsmaskering en alternatieve afbeeldingen worden niet ondersteund.
`writeHTML()`	ln, fill, reseth, cell, align	NextPDF `writeHtml()` verwerkt alleen inhoud. Gebruik de moderne API om HTML in een gepositioneerd blok te plaatsen en de lay-out te sturen.
`writeHTMLCell()`	border (stringvorm), ln, fill, reseth, autopadding	Breedte, hoogte, positie en een booleaanse rand worden gehonoreerd; rijkere celopmaak heeft geen toewijzing.
`ImageEps()`	link, useBoundingBox, align, palign, border, fitonpage, fixoutvals	Alleen positie en grootte worden gehonoreerd.
`ImageSVG()`	link, align, palign, border, fitonpage	Alleen positie en grootte worden gehonoreerd.
`SetProtection()`	mode (niet-nul), pubkeys (niet-leeg)	NextPDF gebruikt altijd AES-256 voor de standaardhandler. Gebruik voor certificaatgebaseerde versleuteling de moderne `setPublicKeyEncryption()` die op de adapter beschikbaar is (zie /integrations/tcpdf-compat/security-and-operations/).
`Bookmark()`	style, color, x, isNamedDest	Titel, niveau en y-positie worden gehonoreerd.
`setDestination()`	page, x	Naam en y-positie worden gehonoreerd.
`Link()`	spaces	TCPDF-interne witruimtebijhouding; geen engine-equivalent.
`Annotation()`	optiesleutels buiten Subtype, spaces	Type, positie en tekst worden gehonoreerd.
`SetLineStyle()`	detail van het streeppatroon buiten breedte	Kernlijneigenschappen worden toegewezen.
`setAlpha()`	gedeeltelijke blend-mode-toewijzing	Sommige blend-mode-namen hebben geen engine-equivalent.
`Polycurve()`	volledige parameterlijst	No-op in de standaardmodus; geen engine-equivalent.
`PieSectorXY()`	volledige parameterlijst	Gedeeltelijke toewijzing (lijnen van middelpunt naar rand verschillen).
`RoundedRectXY()`	straal per hoek	Alleen uniforme hoekstraal.

Hoe de adapter deze verschillen kenbaar maakt, hangt af van de strikte modus (zie /integrations/tcpdf-compat/configuration/). Wanneer de strikte modus uit staat, de achterwaarts compatibele standaard, degraderen deze aanroepen stilzwijgend. Wanneer de strikte modus aan staat, werpt elke aanroep die een parameter negeert een TcpdfNotImplementedException met de exacte lijst van genegeerde parameters en een migratiehint. De strikte modus is een audithulpmiddel, geen productie-instelling.

De strikte modus is ontworpen volgens het principe dat een aanroeper moet kunnen waarnemen wanneer zijn intentie niet is gehonoreerd. OWASP ASVS 5.0 §16.5.3 stelt dat applicaties soepel en veilig moeten falen en fail-open-condities moeten voorkomen. Stil parameterverlies is een probleem voor de ontwikkelaarservaring in plaats van een kwetsbaarheid, maar hetzelfde principe van expliciet falen is van toepassing. De vastgezette clausuledigest staat in de frontmatter citations van de pagina.

3. Niet-geïmplementeerde methoden — lege bodies

Vier methoden bestaan zodat verouderde broncode compileert, maar hun bodies doen niets. Met de strikte modus aan werpen drie ervan een TcpdfNotImplementedException. De vierde (Open()) is een bewuste, veilige no-op die nooit werpt, omdat u deze altijd veilig uit verouderde code kunt verwijderen.

TCPDF-methode	Gedrag	Vervanging
`setSignature()`	No-op (slaat niets op dat tot een actie leidt). Werpt in de strikte modus.	Voor digitale ondertekening is een commerciële NextPDF-editie vereist. Gebruik de moderne handtekening-API met een `CertificateInfo`-waardeobject; zie /integrations/tcpdf-compat/security-and-operations/.
`addEmptySignatureAppearance()`	No-op. Werpt in de strikte modus.	Dezelfde commerciële-editiegrens als `setSignature()`.
`endPage()`	No-op. Werpt in de strikte modus.	NextPDF beheert de paginalevenscyclus automatisch. Verwijder de aanroep.
`Open()`	Veilige no-op. Werpt nooit.	NextPDF opent het document automatisch. Het verwijderen van de aanroep is altijd veilig.

Ondertekening is via deze adapter niet beschikbaar in de kernengine. De adapter stelt een modern toegangspunt voor handtekeningen beschikbaar dat naar de engine delegeert. Basisondersteuning voor handtekeningen is voorbehouden aan een commerciële editie. Deze documentatie doet geen uitspraak over langetermijnvalidatie of handtekeningprofielen met timestamp voor enige editie. Zie /integrations/tcpdf-compat/security-and-operations/ voor de exacte, behoudende formulering.

4. Niet-toepasselijke methoden

Zeven TCPDF-methoden hebben geen effect op de PDF-uitvoer en zijn opzettelijk uitgesloten. U kunt ze veilig aanroepen.

TCPDF-methode	Reden voor uitsluiting
`setDocCreationTimestamp()` / `setDocModificationTimestamp()`	De waarde wordt op de adapter bewaard, maar is niet gekoppeld aan de XMP-metadata van het document. Niet zichtbaar in de uitvoer.
`setSRGBmode()`	Het kleurbeheer van NextPDF staat los van deze vlag.
`setPDFVersion()`	NextPDF selecteert de PDF-versie op basis van het conformance/output-profiel; er is geen directe setter. De adapter geeft een melding en gaat door.
`setDocInfoUnicode()`	NextPDF is altijd Unicode; de vlag is door het ontwerp een no-op.
`setDefaultMonospacedFont()`	Geen engine-equivalent; in plaats daarvan geldt HTML/CSS-styling.
`setFontSubsetting()`	NextPDF maakt altijd subsets van ingesloten lettertypen; de vlag staat in feite altijd aan.

De PDF-versie wordt vastgesteld door de engine. De uitvoer wordt geschreven als PDF 2.0 (ISO 32000-2). ISO 32000-2 §7.5.2 bepaalt dat een conforme writer de documentversie — in de bestandsheader of in de catalogusvermelding Version — identificeert als 2.0. Het bepaalt ook dat het opslaan van een bestand de versie van het bestand niet verlaagt. Dat komt overeen met het gedrag van de adapter: aanroepen zoals setPDFVersion('1.4') kunnen via deze adapter geen oudere PDF-versie als doel instellen. De vastgezette clausuledigest staat in de frontmatter citations van de pagina.

5. Methoden door moderne-API-drift

Zeventien methoden uit NextPDF core v5.1+ zijn op de adapter beschikbaar gesteld (trait AdaptsDriftV51), zodat code die de TCPDF-API met de moderne API combineert nog steeds compileert. Deze hebben geen TCPDF 6.x-equivalent. Voorbeelden: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). Behandel deze als onderdeel van de moderne API, niet als onderdeel van het TCPDF-compatibiliteitscontract.

6. Richtlijnen voor afschaffing en vervanging

Als uw code … aanroept	Status	Doe dit in plaats daarvan
`Error()`	Gedrag gewijzigd (gehard)	De adapter vervangt TCPDF’s `die()` door een geworpen `RuntimeException`. Zet riskante aanroepen in `try`/`catch`; vertrouw niet op procesbeëindiging.
`setPDFVersion()`	Niet van toepassing	Verwijderen. De uitvoer is altijd PDF 2.0.
`setUserRights()`	Afgeschaft in PDF 2.0	Verwijderen. De aanroep geeft een `E_USER_DEPRECATED`-melding en wordt genegeerd.
`setSignature()`	Niet geïmplementeerd in core	Migreer naar de moderne handtekening-API op een commerciële editie.
`Image(...)` met extra parameters	Stil genegeerd	Beperk tot file, x, y, w, h; voeg `Document::link()` toe voor klikbare afbeeldingen.
`endPage()` / `Open()`	Niet geïmplementeerd / no-op	Verwijderen.

7. Veilige migratiestappen

Installeer het pakket en voer uw bestaande suite zonder codewijzigingen uit tegen de adapter. Zie /integrations/tcpdf-compat/install/ en /integrations/tcpdf-compat/quickstart/.
Schakel de strikte modus in tijdens een speciale auditrun (niet in productie): $pdf->setStrictMode(true);. Verzamel elke TcpdfNotImplementedException. Elke uitzondering vermeldt de exacte genegeerde parameters en een migratiehint.
Kies voor elke aanroepplaats of u de genegeerde parameter laat vallen of die aanroep migreert naar de moderne API via $pdf->getDocument().
Maak voor elke test die exacte PDF-bytes controleert een nieuwe baseline; controleer in plaats daarvan op gerenderde inhoud of structurele eigenschappen.
Schakel de strikte modus uit en implementeer het geauditeerde codepad. Laat een periodieke CI-taak met de strikte modus aan staan om regressies op te sporen terwijl u refactort.

Volledige procedure met code: /integrations/tcpdf-compat/migration/.

Zie ook

docs/TCPDF_COVERAGE.md — gezaghebbende, met tests geverifieerde dekkingsmatrix (in de repository)
/integrations/tcpdf-compat/migration/ — end-to-end-migratiestrategie van TCPDF naar NextPDF
/integrations/tcpdf-compat/configuration/ — strikte modus en adapterconfiguratie
/integrations/tcpdf-compat/security-and-operations/ — versleutelings- en handtekeningbeleid
/integrations/tcpdf-compat/integration/ — de adapter in een applicatie bedraden
/integrations/tcpdf-compat/boot-and-discovery/ — registratie van class-aliassen en beschikbaarstelling van de facade