NextPDF compat-legacy: boot en detectie

In één oogopslag

nextpdf/compat-legacy stelt NextPDF\Compat\Tcpdf\TCPDF beschikbaar: een TCPDF-compatibele facade die delegeert aan de NextPDF-engine. Het is een compatibiliteitslaag, geen drop-in-kloon. De facade delegeert 94 van de ongeveer 120 onderzochte TCPDF 6.x-methoden rechtstreeks. Voor de overige methoden zijn de gedragsverschillen gedocumenteerd; zie /integrations/tcpdf-compat/method-coverage/.

Er is geen globale koppeling tijdens autoload. Het laden van het pakket maakt standaard geen globale \TCPDF-klasse aan. U kiest expliciet voor globale aliassen, of importeert tijdens de migratie bij voorkeur per bestand de adapterklasse.

Hoe de TCPDF-facade beschikbaar wordt gesteld

De facade is een standaardklasse die via PHP Standard Recommendation 4 (PSR-4) automatisch wordt geladen:

Item	Waarde
Facadeklasse	NextPDF\Compat\Tcpdf\TCPDF
PSR-4-prefix	NextPDF\Compat\Tcpdf\ verwijst naar src/Compat/Tcpdf/
Gedeeld contract	NextPDF\Compat\Contracts\CompatAdapterInterface
Ontsnappingsroute	TCPDF::getDocument() geeft het ingepakte NextPDF\Core\Document terug

De klasse is bewust niet final. Legacy TCPDF-gebruikers maken vaak een subklasse van TCPDF om Header() en Footer() te overschrijven, en de adapter behoudt dat uitbreidingspunt. Intern fungeert de klasse als een facade. Ze combineert 25 concern-traits met elk één verantwoordelijkheid en delegeert alle Portable Document Format (PDF)-bewerkingen aan een Document-instantie die bij het opbouwen van de facade wordt aangemaakt.

Boot-volgorde

Diagram

De constructie is de enige bootstap. Het pakket zelf registreert geen servicecontainer en voert geen framework-bootstrapping uit. U voegt framework-integratie toe als dunne laag; zie /integrations/tcpdf-compat/integration/.

LegacyDefaults::register() is idempotent: het definieert een constante alleen wanneer die constante nog niet is gedefinieerd. Constanten die de applicatie definieert, hebben altijd voorrang als u ze vóór de eerste constructie definieert; zie /integrations/tcpdf-compat/configuration/ § Configuration resolution order.

Globale klasse-aliassen op aanvraag

Als uw codebase new \TCPDF(...) in de globale namespace aanroept en u die aanroeppunten nog niet kunt wijzigen, registreer dan één keer globale aliassen tijdens de applicatie-boot:

examples/boot-aliases.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() registreert \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS en \TCPDF_IMAGES. tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php bevestigt dit gedrag:

• Het is idempotent: twee keer aanroepen veroorzaakt geen fout en registreert maar één keer.
• LegacyBootstrap::isRegistered() geeft aan of het is uitgevoerd.
• Na registratie maakt new \TCPDF() een instantie van de adapter aan.

Conflictpreventie met een echte TCPDF-installatie

Dit is de allerbelangrijkste regel op deze pagina.

enableAliases() registreert een alias alleen als er nog geen klasse met die naam bestaat (class_exists($alias, autoload: false)). Dat betekent:

• Als tecnickcom/tcpdf is geïnstalleerd en de bijbehorende \TCPDF-klasse als eerste wordt geladen, wordt de alias stilzwijgend overgeslagen en blijft uw code legacy TCPDF gebruiken in plaats van de adapter.
• Beide bibliotheken in hetzelfde proces uitvoeren met globale aliassen ingeschakeld wordt niet ondersteund en leidt tot dubbelzinnig gedrag.

Geef tijdens de migratie de voorkeur aan expliciete imports per bestand (use NextPDF\Compat\Tcpdf\TCPDF;). Die zijn eenvoudig te doorzoeken en ondubbelzinnig. Verwijder tecnickcom/tcpdf zodra de strict-mode-audit slaagt; zie /integrations/tcpdf-compat/migration/ Stage 5. Wanneer \TCPDF naar de verkeerde klasse verwijst, helpt /integrations/tcpdf-compat/troubleshooting/ met de diagnose.

Containerbindingen

Het pakket levert geen framework-containerbindingen mee. Als u de facade in een container bindt, bind dan een factory die voor elk document een nieuwe NextPDF\Compat\Tcpdf\TCPDF teruggeeft. De documentstatus hoort bij de instantie en mag niet worden gedeeld tussen niet-gerelateerde documenten; zie /integrations/tcpdf-compat/production-usage/ § Concurrency. /integrations/tcpdf-compat/integration/ toont een typische binding.

Volgorde van configuratieresolutie

Tijdens de constructie lost de adapter de configuratie in deze volgorde op: eerst de constructorargumenten, daarna eventuele bestaande, door de applicatie gedefinieerde legacy-constanten, en vervolgens de TCPDF 6.2.13-standaardwaarden uit LegacyDefaults voor elke constante die nog niet is gedefinieerd. Zie voor volledige details en het moderne AdaptationConfig-object /integrations/tcpdf-compat/configuration/.

Diagnostiek

Om te bevestigen dat de facade is gekoppeld en de engineverbinding goed wordt opgelost, construeert u een adapter, produceert u een PDF van één pagina en controleert u de %PDF-prefix. De uitvoertests van het pakket valideren hetzelfde oppervlak. De uitvoerbare controle staat in /integrations/tcpdf-compat/install/ § Verify the installation.

Om een conflict met een echte TCPDF te detecteren voordat u aliassen inschakelt, controleert u of er al een globale \TCPDF bestaat op de plek waar u enableAliases() zou aanroepen. Als dat zo is, wordt de alias overgeslagen. Los het conflict op met expliciete imports of verwijder de echte TCPDF voordat u op de adapter vertrouwt.

TCPDF API-dekking

De gezaghebbende, met tests geverifieerde dekkingsmatrix is het bestand docs/TCPDF_COVERAGE.md in de repository. De lezersgerichte samenvatting, inclusief de lijsten met stilzwijgend genegeerde en niet-geïmplementeerde methoden, is /integrations/tcpdf-compat/method-coverage/. Dit pakket beweert niet dat het een drop-in-vervanger of 100% TCPDF-compatibel is; het is een TCPDF-compatibel alternatief met een bekend en getest compatibiliteitsoppervlak en gedocumenteerde gedragsverschillen.

Zie ook

• docs/TCPDF_COVERAGE.md — gezaghebbende dekkingsbron (in de repository)
• /integrations/tcpdf-compat/integration/ — de facade koppelen in een applicatie/framework
• /integrations/tcpdf-compat/method-coverage/ — gedrag en hiaten per methode
• /integrations/tcpdf-compat/migration/ — gefaseerde migratiestrategie
• /integrations/tcpdf-compat/troubleshooting/ — diagnose van aliasconflicten en conflicten met echte TCPDF
• tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — test-oracle voor aliasgedrag