Snelstart voor compat-legacy

In een oogopslag

Deze pagina begeleidt u van een geïnstalleerd package naar een voltooide PDF en daarna naar de strict-modus-audit die u vóór de migratie uitvoert. Elk codeblok komt overeen met gedrag dat door de testsuite van het package wordt vastgelegd; de uitvoer die hier wordt getoond, is dus de uitvoer die de tests controleren.

Voordat u begint

Volg /integrations/tcpdf-compat/install/ om het package te installeren en de engine-koppeling te bevestigen. U hebt PHP 8.4 nodig en nextpdf/core ^3.0 moet zijn opgelost.

1. Maak uw eerste document

Pas de import aan en behoud uw aanroepen in TCPDF-stijl. Dit is exact de interface die door tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php wordt vastgelegd.

examples/quickstart-first.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

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

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

Voer het script uit:

php examples/quickstart-first.php

Het bestand quickstart.pdf is een geldige PDF 2.0. De testsuite legt vast dat de bijbehorende string-uitvoer begint met %PDF voor de bestemmingen S, F en E en voor getPDFData().

Uitvoerbestemmingen

Output($name, $dest) koppelt de TCPDF-bestemmingscodes via een veilige uitvoerbrug. De testsuite controleert dit gedrag:

$dest	Gedrag	Retourneert
'S'	Retourneert de PDF als string	PDF-bytes (%PDF…)
'F'	Schrijft de PDF naar het opgegeven pad	lege string
'E'	Retourneert een base64-MIME-body	een blok met Content-Type: application/pdf
'I'	Inline (standaard)	volgens de uitvoerbrug
'D'	Downloaden	volgens de uitvoerbrug

In tegenstelling tot de oude TCPDF schrijft Output() niet rechtstreeks naar de actieve uitvoerbuffer. U kunt de methode veilig aanroepen vanuit een queue-worker of een HTTP-handler die zijn eigen respons beheert. Zie /integrations/tcpdf-compat/production-usage/.

2. Voer bestaande TCPDF-code ongewijzigd uit

Begin een echte migratie door uw bestaande code uit te voeren terwijl u alleen de import of de alias wijzigt. Als uw codebase new \TCPDF(...) in de globale namespace aanroept, schakel dan eenmalig bij het opstarten de opt-in-aliassen in (beschreven in /integrations/tcpdf-compat/boot-and-discovery/):

examples/quickstart-alias.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

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

LegacyBootstrap::enableAliases() is idempotent. Het registreert \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS en \TCPDF_IMAGES alleen wanneer die klassen nog niet bestaan. De test tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php legt vast dat de aliassen worden geregistreerd, dat de aanroep idempotent is en dat new \TCPDF() een adapter-instantie is. Schakel de aliassen niet in als de echte TCPDF-bibliotheek in hetzelfde proces is geladen; zie /integrations/tcpdf-compat/troubleshooting/.

3. Audit met strict-modus

Deze stap maakt een migratie veiliger. Wanneer strict-modus is uitgeschakeld (de standaard), gebruiken methoden die TCPDF-gedrag niet kunnen reproduceren stilzwijgend de fallback. Wanneer strict-modus is ingeschakeld, gooien ze TcpdfNotImplementedException met de exacte genegeerde parameters. Voer dit uit in een aparte auditronde, nooit in productie.

examples/quickstart-strict-audit.php

<?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 {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

De test tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php legt vast dat precies deze aanroep in strict-modus een exception gooit, in de standaardmodus stil blijft, en dat het bericht de methodenaam en de genegeerde parameters bevat. Gebruik de verzamelde exceptions als uw migratiewerklijst — zie /integrations/tcpdf-compat/migration/.

4. Gebruik de moderne API wanneer u die nodig hebt

Elke adapter-instantie stelt het onderliggende engine-document beschikbaar. Gebruik dit om moderne NextPDF-methoden aan te roepen die geen TCPDF-equivalent hebben:

examples/quickstart-escape-hatch.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument() retourneert de NextPDF\Core\Document die door de adapter wordt omhuld. Dit is de aanbevolen uitwijkroute: verplaats uw aanroeplocaties één voor één naar de moderne API, totdat u de adapter kunt verwijderen.

Gedragsverschillen die u meteen kunt verwachten

• MultiCell() retourneert 1, niet het aantal weergegeven cellen. Code die vertakt op basis van de retourwaarde van MultiCell() moet worden aangepast.
• Error() gooit RuntimeException in plaats van die() aan te roepen. Code die vertrouwde op procesbeëindiging moet de exception opvangen.
• De exacte PDF-bytes verschillen van de TCPDF-uitvoer. Werk testassertions op byte-niveau bij naar een nieuwe baseline, zodat ze in plaats daarvan de weergegeven inhoud controleren.

De volledige lijst per methode staat in /integrations/tcpdf-compat/method-coverage/.

Volgende stappen

• /integrations/tcpdf-compat/migration/ — de volledige migratiestrategie, bestand voor bestand.
• /integrations/tcpdf-compat/configuration/ — strict-modus, standaardwaarden en het moderne configuratie-object.
• /integrations/tcpdf-compat/production-usage/ — workers, uitvoerbuffers en prestaties.
• /integrations/tcpdf-compat/security-and-operations/ — versleutelings- en ondertekeningsbeleid.

Zie ook

• tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — oracle voor uitvoergedrag
• tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — oracle voor strict-modus
• docs/TCPDF_COVERAGE.md — gezaghebbende dekkingsmatrix