Problemen oplossen met compat-legacy

In één oogopslag

De meeste migratieproblemen vallen binnen een klein aantal patronen. Elk item hieronder vermeldt het symptoom, de oorzaak en de oplossing. Als je twijfelt over een specifieke methode, raadpleeg dan /integrations/tcpdf-compat/method-coverage/ en de gezaghebbende matrix in de repo docs/TCPDF_COVERAGE.md.

Het proces stopte voorheen bij een PDF-fout; nu wordt er een uitzondering doorgegeven

Symptoom. Code die voorheen stopte wanneer de weergave mislukte, werpt nu een niet-afgevangen RuntimeException, waarna het verzoek of de taak een fout meldt.

Oorzaak. Verouderde TCPDF-aanroepen naar Error() roepen die() aan. De adapter werpt in plaats daarvan bewust RuntimeException, zodat fouten zichtbaar zijn.

Oplossing. Omsluit de plekken waar je PDF’s rendert met try/catch en vertaal de uitzondering naar je foutcontract. Herstel het gedrag van die() niet. Zie /integrations/tcpdf-compat/production-usage/ § Foutafhandeling.

`new \TCPDF()` verwijst nog steeds naar de echte TCPDF-bibliotheek

Symptoom. Je hebt LegacyBootstrap::enableAliases() ingeschakeld, maar de uitvoer ziet er nog steeds uit als verouderde TCPDF, of het gedrag is niet veranderd.

Oorzaak. enableAliases() registreert alleen een alias wanneer er nog geen klasse met die naam bestaat. Als tecnickcom/tcpdf autoloadbaar blijft en de \TCPDF-klasse ervan eerst wordt geladen, wordt de alias overgeslagen en blijft je code verouderde TCPDF gebruiken.

Oplossing. Gebruik tijdens de migratie expliciete imports per bestand (use NextPDF\Compat\Tcpdf\TCPDF;) zodat elke aanroeplocatie ondubbelzinnig is. Verwijder tecnickcom/tcpdf nadat de audit is geslaagd (zie /integrations/tcpdf-compat/migration/ Fase 5). Voer niet beide bibliotheken in hetzelfde proces uit terwijl globale aliassen zijn ingeschakeld.

Een methode “werkt”, maar de parameter die ik heb doorgegeven wordt genegeerd

Symptoom. Een aanroep slaagt en produceert een Portable Document Format (PDF)-bestand, maar een optie die je hebt doorgegeven (afbeeldingslink, uitlijning, dots per inch (DPI), bladwijzerkleur, …) heeft geen effect.

Oorzaak. De methode valt onder de set die stil wordt genegeerd. De methode accepteert de parameter vanwege broncompatibiliteit en laat hem vervolgens vallen. Dit is gedocumenteerd gedrag, geen bug; zie /integrations/tcpdf-compat/method-coverage/ §2.

Oplossing. Voer een audit in strikte modus uit om elke dergelijke aanroep te vinden:

<?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('logo.png', 10, 10, 50, 0, '', 'https://example.com');
} catch (TcpdfNotImplementedException $e) {
    // Message lists every ignored parameter and a migration hint.
    echo $e->getMessage(), "\n";
}

Laat de parameter daarna weg, of druk de intentie ervan opnieuw uit via de moderne API ($pdf->getDocument()), zoals getoond in /integrations/tcpdf-compat/migration/ Fase 4.

`MultiCell()` geeft altijd 1 terug

Symptoom. Code die op basis van de retourwaarde van MultiCell() vertakt (bijvoorbeeld om de gebruikte hoogte of het aantal regels te berekenen), gedraagt zich onjuist.

Oorzaak. De adapterversie van MultiCell() geeft de compatibiliteitsplaatshouder 1 terug, niet het weergegeven aantal cellen of regels. Evenzo geeft Write() 0 terug.

Oplossing. Vertak niet op deze retourwaarden. Als je de weergegeven hoogte nodig hebt, bereken die dan op basis van getStringHeight() / getNumLines(), of verplaats die logica naar de moderne API.

`setPDFVersion('1.4')` produceerde geen PDF 1.4-bestand

Symptoom. Je hebt om een oudere PDF-versie gevraagd; de uitvoer is nog steeds PDF 2.0.

Oorzaak. De adapter levert altijd PDF 2.0 (ISO 32000-2). setPDFVersion() valt onder de niet-van-toepassing-set; de adapter geeft een melding en gaat verder.

Oplossing. Verwijder de aanroep. Als een downstream-consument een oudere PDF-versie vereist, los die vereiste dan afzonderlijk op; de adapter kan niet naar een lagere versie terugschakelen.

`setSignature()` deed niets — de PDF is niet ondertekend

Symptoom. Je hebt setSignature() met een certificaat aangeroepen; de uitvoer-PDF heeft geen handtekening.

Oorzaak. De kern-engine implementeert setSignature() niet via deze adapter. In de standaardmodus is het een no-op; in de strikte modus werpt de aanroep een uitzondering.

Oplossing. Voor ondertekenen heb je een commerciële NextPDF-editie en de moderne handtekening-API nodig. Zie /integrations/tcpdf-compat/security-and-operations/ § Digitale handtekeningen. Verwacht niet dat de verouderde aanroep van setSignature() iets ondertekent.

`Output()` beschadigde mijn HTTP-respons of worker-uitvoer

Symptoom. PDF-bytes verschijnen in een Hypertext Transfer Protocol (HTTP)-respons, of een worker-logboek raakt vervuild met PDF-bytes.

Oorzaak. Je hebt een uitvoerbestemming gebruikt die naar het uitvoerpad schrijft (I/D) terwijl je de respons zelf beheert. De adapter echoot niet in je buffer zoals verouderde TCPDF dat doet, maar I/D activeren nog steeds de engine-uitvoer.

Oplossing. Gebruik in workers en handlers die je beheert Output($path, 'F') om een bestand te schrijven, of Output($name, 'S') om de bytes op te halen en zelf uit te sturen. tests/Unit/Compat/Tcpdf/Bridge/OutputBridgeTest.php bevestigt dat de bestemmingstoewijzing niet hoofdlettergevoelig is en dat witruimte wordt verwijderd:

Code	Geeft terug	Neveneffect
`S`	PDF-bytes (`%PDF…`)	geen
`F`	lege tekenreeks	schrijft bestand
`E`	base64-MIME-body	geen
`FI` / `FD`	lege tekenreeks	schrijft bestand, daarna engine-uitvoer
`I` / `D` / onbekend	lege tekenreeks	engine-uitvoer (inline/download)

PDF-asserties op exacte bytes mislukken na het overschakelen

Symptoom. Snapshot-tests die ruwe PDF-bytes vergelijken mislukken overal.

Oorzaak. De engine gebruikt een onafhankelijke PDF 2.0-implementatie. Gedelegeerde methoden produceren zichtbaar compatibele uitvoer, maar de bytes verschillen. Dat is verwacht gedrag.

Oplossing. Stel een nieuwe basislijn voor je tests in zodat ze asserteren op weergegeven inhoud (geëxtraheerde tekst), structuur (aantal pagina’s, paginaformaat) of een rooktest (str_starts_with($bytes, '%PDF')). Zie /integrations/tcpdf-compat/migration/ Fase 4.

Een verouderde `K_` / `PDF_`-constante heeft de verkeerde waarde

Symptoom. Een aangepast pad of een aangepaste standaardwaarde die je via een constante hebt ingesteld, wordt niet van kracht.

Oorzaak. De adapter definieert een constante alleen automatisch als die nog niet is gedefinieerd, en doet dat bij de eerste constructie. Als je define() wordt uitgevoerd nadat de eerste adapter is geconstrueerd, is de standaardwaarde van de adapter al van kracht.

Oplossing. Definieer elke aangepaste K_* / PDF_*-constante in je bootstrap, voordat er een adapter-instantie wordt aangemaakt. Zie /integrations/tcpdf-compat/configuration/ § Volgorde van configuratieoplossing.

Engine-versie komt niet overeen bij constructie

Symptoom. De constructie mislukt of het gedrag verandert onverwacht na een afhankelijkheidsupdate.

Oorzaak. De adapter vereist nextpdf/core ^3.0. Een core-versie buiten dat bereik wordt niet ondersteund.

Oplossing. Voer composer show nextpdf/core uit en pin de engine op ^3.0. Zie /integrations/tcpdf-compat/install/ § De engine-versie verifiëren.

Snelle diagnostische referentie

Vraag	Waar te kijken
Wat doet methode X hier eigenlijk?	/integrations/tcpdf-compat/method-coverage/, `docs/TCPDF_COVERAGE.md`
Welke van mijn aanroepen verliezen parameters?	Audit in strikte modus (deze pagina; /integrations/tcpdf-compat/migration/)
Waarom stopte het proces niet bij een fout?	/integrations/tcpdf-compat/security-and-operations/ § Geharde gedragingen
Waarom is de uitvoer niet ondertekend / waarom is het geen PDF/A?	/integrations/tcpdf-compat/security-and-operations/
Conflict tussen alias en expliciete import	Deze pagina; /integrations/tcpdf-compat/boot-and-discovery/

Zie ook

/integrations/tcpdf-compat/migration/ — de gefaseerde migratie die de meeste bovenstaande problemen voorkomt
/integrations/tcpdf-compat/method-coverage/ — gedragsreferentie per methode
/integrations/tcpdf-compat/boot-and-discovery/ — aliasregistratie en conflictvermijding
docs/TCPDF_COVERAGE.md — gezaghebbende dekkingsmatrix