TCPDF-compatibiliteits-API: referentie

In een oogopslag

Het pakket nextpdf/compat-legacy biedt één hoofdklasse: NextPDF\Compat\Tcpdf\TCPDF. Deze volgt de publieke application programming interface (API) van TCPDF 6.x, maar rendert met de moderne NextPDF-engine. Het pakket bevat ook een klein ondersteunend oppervlak: LegacyBootstrap voor globale klasse-aliassen, het configuratieoppervlak AdaptationConfig/LegacyDefaults, interne bridge-klassen voor uitvoer, constructie, kleur, eenheden en paginaformaten, en compatibiliteits-exceptions. Gebruik het als migratiehulpmiddel, niet als permanente afhankelijkheid. De tabel met methodedekking is de bron voor de volledige status van verouderde methoden. Deze pagina documenteert alleen de oppervlakken waarvan applicatiecode bewust afhankelijk hoort te zijn.

Begin hier: Als dit pakket nieuw voor u is, construeer dan NextPDF\Compat\Tcpdf\TCPDF, voer uw gebruikelijke TCPDF-aanroepen uit (AddPage(), SetFont(), Cell()) en sluit af met Output($name, $dest). Die klasse is het toegangspunt voor vrijwel alles wat hierna volgt. Voor uitvoerbare startpunten, zie Veelvoorkomende taken.

Veelvoorkomende taken

Dit zijn de taken in het pakket die u het vaakst gebruikt. Elk blok is geverifieerd aan de adapterbroncode en draait zonder aanpassing.

Maak een Portable Document Format (PDF)-bestand met vertrouwde TCPDF-aanroepen en verkrijg het vervolgens als string voor een wachtrij, een HTTP-respons of opslag:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

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

$bytes = $pdf->Output('invoice.pdf', 'S');

Wat het doet: bouwt een PDF 2.0-document met de TCPDF-vormige adapter. Het retourneert de ruwe bytes (%PDF...) omdat bestemming 'S' via OutputBridge naar Document::getPdfData() leidt in plaats van ze uit te echoën. Daardoor is dit veilig binnen een worker of controller.

Registreer de globale aliassen eenmalig tijdens het opstarten om bestaande new \TCPDF(...)-code zonder broncodewijzigingen uit te voeren:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

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

Wat het doet: enableAliases() registreert idempotent \TCPDF (en de helpers \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES) alleen wanneer die namen nog niet gedefinieerd zijn. Ongewijzigde verouderde code draait dan op de adapter.

Voer een migratie-audit uit door elke TCPDF-parameter zichtbaar te maken die de adapter anders stilzwijgend zou laten vallen:

<?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 {
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter
}

Wat het doet: met setStrictMode(true) werpt een aanroep die het TCPDF-gedrag niet kan reproduceren TcpdfNotImplementedException en vermeldt elke genegeerde parameter. Hiermee wordt stille degradatie omgezet in een migratiewerklijst. Voer dit alleen uit tijdens een auditronde, nooit in productie.

Hoofdadapter

Deze tabel beschrijft het canonieke adapteroppervlak. Gebruik deze om te bepalen welke klasse u construeert (TCPDF), welke strict-mode- en escape-hatch-methoden beschikbaar zijn en welk contract de klasse implementeert.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
NextPDF\Compat\Tcpdf\TCPDF	Constructorparameters volgen de verouderde TCPDF-vorm via ConstructorBridge.	Maakt een adapter die wordt ondersteund door een NextPDF-document.	TCPDF	Constructorvalidatie- of niet-ondersteunde-functie-exceptions.	Gebruik tijdens migratie, niet voor nieuwe native NextPDF-code.
TCPDF::getDocument()	geen.	Retourneert het onderliggende NextPDF-document.	NextPDF\Core\Document	geen verwacht.	Gebruik als escape hatch voor migratiecode die verouderde en native aanroepen moet combineren.
TCPDF::getUnitConverter()	geen.	Retourneert de converter die uit de verouderde eenheid is gemaakt.	UnitConverter	geen verwacht.	Gebruik voor migratiediagnostiek, niet voor normale applicatiecode.
TCPDF::setStrictMode(bool $enabled)	Strict-mode-vlag.	Schakelt expliciet falen voor niet-ondersteund compatibiliteitsgedrag in of uit.	static	geen verwacht.	Houd ingeschakeld tijdens migratie-audits.
TCPDF::isStrictMode()	geen.	Retourneert de huidige strict-mode-vlag.	bool	geen verwacht.	Handig in testasserties.
TCPDF-verouderde methoden	Verschilt per methode.	Ondersteunde methoden worden gekoppeld aan core-documentaanroepen; niet-ondersteunde methoden falen expliciet.	Verschilt per methode.	TcpdfNotImplementedException of UnsupportedFeatureException.	Controleer methodedekking voordat u op een methode vertrouwt.
CompatAdapterInterface::getDocument()	geen.	Contractmethode geïmplementeerd door TCPDF.	Document	geen verwacht.	Stelt tooling in staat het native document te bereiken.
CompatAdapterInterface::Output(string $name = '', string $dest = '')	Bestandsnaam en verouderde bestemming.	Delegeert naar de output bridge.	string	Core-schrijffouten of fouten door een niet-ondersteunde bestemming.	Weerspiegelt de verouderde TCPDF-uitvoer; de concrete TCPDF::Output levert de standaardwaarden 'doc.pdf'/'I'.

Verouderde methodegroepen

Deze tabel brengt de TCPDF-methodefamilies in kaart die de adapter dekt. Gebruik deze om een verouderde aanroep te vinden voordat u de exacte status ervan in de methodedekking controleert.

Groep	Representatieve symbolen	Standaardgedrag	Opmerkingen
Levenscyclus en uitvoer	Open(), Close(), Output(), getPDFData()	Houdt een TCPDF-vormige documentlevenscyclus bij bovenop een native document.	Geef na migratie de voorkeur aan native uitvoer-API’s.
Metadata	SetTitle(), SetAuthor(), SetSubject(), SetKeywords(), SetCreator()	Koppelt metadata-setters aan het onderliggende document.	Houd metadatanormalisatie in de applicatiecode.
Pagina’s en positionering	AddPage(), setPage(), lastPage(), GetX(), SetXY()	Converteert verouderde eenheden en coördinaten naar native pagina-operaties.	Verifieer absolute positionering visueel na migratie.
Marges en lay-out	SetMargins(), SetAutoPageBreak(), setCellPaddings(), getMargins()	Slaat compatibiliteitstoestand op en koppelt ondersteunde waarden.	Complex TCPDF-pagina-afbrekingsgedrag kan handmatige beoordeling vereisen.
Lettertypen en tekst	SetFont(), AddFont(), Cell(), MultiCell(), Write(), Text()	Leidt veelvoorkomende tekstoperaties naar native lettertype- en tekst-API’s.	Controleer CJK- en coderingsgedrag met productielettertypen.
HTML	writeHTML(), writeHTMLCell(), fixHTMLCode()	Geeft ondersteunde HTML door aan de native HTML-pijplijn.	De native renderer is geen volledige TCPDF-HTML-kloon.
Afbeeldingen en tekenen	Image(), Line(), Rect(), Circle(), SetDrawColor()	Koppelt ondersteunde grafische operaties via adapter-concerns.	Niet-ondersteunde vectorformaten of speciale formaten falen expliciet.
Navigatie en annotaties	Bookmark(), AddLink(), SetLink(), Annotation()	Behoudt veelvoorkomende navigatieaanroepen waar deze gekoppeld zijn.	Valideer gegenereerde outlines en koppelingen.
Beveiliging en handtekeningen	SetProtection(), setSignature(), setTimeStamp(), setUserRights()	Verbindt ondersteunde verouderde beveiligingsaanroepen met native functies.	Behandel cryptografische uitvoer als een aparte verificatiepoort.
Formulieren, sjablonen, transformaties	TextField(), startTemplate(), StartTransform(), Rotate(), Scale()	Implementeert ondersteunde subsets en faalt luid bij niet-ondersteund gedrag.	Audit elke aanroep tegen de methodedekking vóór uitrol.

Bootstrap en configuratie

Gebruik deze tabel wanneer u de adapter in het opstartpad van een applicatie inbouwt, globale aliassen registreert of kiest tussen verouderde constanten en het moderne AdaptationConfig.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
LegacyBootstrap::enableAliases()	geen.	Registreert compatibiliteitsaliassen eenmalig.	void	Autoload- of omgevingsfouten.	Gebruik alleen wanneer verouderde code verwacht dat TCPDF-namen globaal bestaan.
LegacyBootstrap::isRegistered()	geen.	Rapporteert of aliassen zijn geregistreerd.	bool	geen verwacht.	Handig in bootstrap-tests.
LegacyBootstrap::resetForTesting()	geen.	Wist de registratietoestand voor tests.	void	geen verwacht.	Helper alleen voor tests.
AdaptationConfig	Adaptervlaggen en migratiebesturingen.	Gebruikt pakketstandaarden wanneer weggelaten.	AdaptationConfig	Ongeldige optiewaarden.	Houd de configuratie expliciet tijdens migratie-audits.
AdaptationConfig::fromLegacyConstants()	geen.	Leest bekende verouderde constanten en bouwt een configuratieobject.	AdaptationConfig	Ongeldige waarden voor verouderde constanten.	Overgangshelper voor grote verouderde applicaties.
LegacyDefaults	geen.	Levert standaard verouderde waarden.	Standaardwaarden.	geen verwacht.	Centrale plek voor compatibiliteitsstandaarden.

Bridges en helpers

Deze interne conversieklassen drijven de adapter aan. Gebruik deze tabel wanneer u bijdraagt aan adapterdekking of vaststelt hoe een verouderd argument wordt vertaald. Geef voor alledaagse applicatiecode de voorkeur aan het publieke adapteroppervlak.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
ConstructorBridge	Lijst met verouderde constructorargumenten.	Normaliseert verouderde opties naar NextPDF-configuratie.	Constructorgegevens.	Ongeldige verouderde argumentwaarden.	Intern gebruikt door de adapter.
CellParameterAdapter	TCPDF-celparameters.	Koppelt verouderde positionele argumenten aan core-tekstlay-outopties.	Aangepaste parameters.	Ongeldige afmetingen of uitlijning.	Geef in nieuwe code de voorkeur aan native core-methoden.
OutputBridge::dispatch(Document $document, string $filename, string $dest)	Native document, bestandsnaam en verouderde bestemming.	Koppelt inline/download/save-gedrag aan NextPDF-uitvoer-API’s.	string	Core-schrijffouten; niet-ondersteunde bestemming.	Valideer bestandsnamen en opslagwortels vóór uitvoer.
OutputBridge::resolveDestination(string $dest)	Verouderde bestemmingscode.	Converteert de bestemming naar een native uitvoerbestemming.	OutputDestination	Fouten door niet-ondersteunde bestemming.	Houdt de bestemmingskoppeling gecentraliseerd.
ColorTranslator	TCPDF-kleurargumenten.	Normaliseert verouderde kleurvormen.	Core-kleurwaarde.	Ongeldige kleurwaarden.	Gebruikt door kleur- en teken-concerns.
PageFormatResolver	Verouderde paginaformaatinvoer.	Koppelt bekende namen aan core-paginaformaten.	Paginaformaatwaarde.	Onbekend formaat.	Gebruik na migratie expliciete native paginaformaten.
UnitConverter	Verouderde meetwaarden en eenheden.	Converteert naar core-eenheden.	Numerieke waarde.	Ongeldige eenheid.	Helpt verouderd lay-outgedrag te behouden.

Exceptions

Gebruik deze tabel wanneer een migratieaanroep luid faalt. De tabel scheidt fouten van het type „niet geïmplementeerd” van fouten van het type „bekend maar niet ondersteund” en toont het herstelpad.

Symbool	Betekenis	Herstel
TcpdfNotImplementedException	De adapter implementeert de gevraagde verouderde methode opzettelijk niet.	Vervang de aanroep door de native NextPDF-API of verwijder de afhankelijkheid.
TcpdfNotImplementedException::forSilentIgnore()	Een verouderde aanroep zou voorheen zijn genegeerd, maar wordt zichtbaar gemaakt voor migratiehelderheid.	Beslis of expliciet no-op-gedrag aanvaardbaar is.
TcpdfNotImplementedException::forUnimplemented()	Een verouderde aanroep heeft geen geïmplementeerd adapterpad.	Vervang de aanroep of isoleer die achter migratiecode.
UnsupportedFeatureException	De verouderde functie is bekend maar wordt niet ondersteund binnen de adaptergrens.	Raadpleeg de migratierichtlijnen en isoleer de functie achter een applicatieadapter.
UnsupportedFeatureException::forMethod()	Maakt een methodespecifieke fout voor een niet-ondersteunde functie.	Gebruik in compatibiliteitsbijdragen om consistente foutmeldingen te behouden.

Ontwikkelnotities

• Behandel de adapter als migratiehulpmiddel. Nieuwe code hoort zich rechtstreeks op core-NextPDF-API’s te richten.
• Niet-ondersteund gedrag hoort luid te falen. Vang compatibiliteits-exceptions niet op om met een gedeeltelijk document door te gaan, tenzij de applicatie dat risico expliciet aanvaardt.
• Houd migratiewijzigingen klein en verifieer elke verouderde methode tegen de dekkingstabel.