compat-legacy draaien in productie

In één oogopslag

U kunt de adapter veilig gebruiken in Hypertext Transfer Protocol (HTTP)-handlers, queueworkers en langlopende processen. Deze is veiliger dan de oude TCPDF 6.2.13, omdat hij de twee productiegevaren wegneemt die u het waarschijnlijkst tegenkomt: rechtstreekse uitvoer naar de buffer, en die() bij een fout. Gebruik deze pagina om hem correct in productie toe te passen.

Rond vóór productie de strict-mode-audit in /integrations/tcpdf-compat/migration/ af en deploy met strict mode uit.

Uitvoerafhandeling in workers en handlers

De oude TCPDF Output() schrijft rechtstreeks naar de actieve uitvoerbuffer. Dat kan responses in HTTP-frameworks beschadigen en queueworkers laten falen. De adapter leidt de uitvoer in plaats daarvan via een veilige bestemmingsbrug.

Kies de bestemming die bij de aanroeper past:

Context	Bestemming	Waarom
Queueworker die naar opslag schrijft	`Output($path, 'F')`	Schrijft het bestand en retourneert een lege string. Dit raakt de buffer niet.
Genereren en daarna attach/upload	`Output($name, 'S')`	Retourneert de Portable Document Format (PDF)-bytes; u bepaalt waar ze naartoe gaan.
E-mailbijlage	`Output($name, 'E')`	Retourneert een base64-gecodeerde Multipurpose Internet Mail Extensions (MIME)-body met `Content-Type: application/pdf`.
HTTP-response die u zelf beheert	`Output($name, 'S')`	Haalt de bytes op, waarna u uw eigen headers en body instelt.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

/**
 * Render an invoice in a queue worker. Returns the storage path.
 *
 * @throws \RuntimeException on a render failure (Error() throws, not die()).
 */
function renderInvoiceJob(array $invoice, string $storageDir): string
{
    $pdf = new TCPDF('P', 'mm', 'A4');
    $pdf->SetFont('helvetica', '', 12);
    $pdf->AddPage();
    $pdf->Cell(0, 10, 'Invoice ' . $invoice['number'], 0, 1);

    $path = $storageDir . '/invoice-' . $invoice['number'] . '.pdf';

    try {
        $pdf->Output($path, 'F'); // writes file, no buffer pollution
    } catch (TcpdfNotImplementedException $e) {
        // Only reachable if strict mode is on — it must NOT be in production.
        throw new \RuntimeException('Adapter strict-mode gap in production: ' . $e->getMessage(), 0, $e);
    } catch (\RuntimeException $e) {
        // Error() throws RuntimeException instead of die().
        throw new \RuntimeException('PDF render failed: ' . $e->getMessage(), 0, $e);
    }

    return $path;
}

Gebruik in een HTTP-handler bij voorkeur 'S' en stel de headers zelf in:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Report');

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

header('Content-Type: application/pdf');
header('Content-Length: ' . strlen($bytes));
header('Content-Disposition: inline; filename="report.pdf"');
echo $bytes;

Foutafhandeling

Error() gooit een RuntimeException; het roept nooit die() aan. Dit is het belangrijkste operationele verschil met de oude TCPDF.

Omhul elk render-instappunt met try/catch.
Koppel de uitzondering aan het foutcontract van uw applicatie, zoals HTTP 5xx, een mislukte job, een retry of een dead-letter.
Ga er niet van uit dat het proces eindigt bij een renderfout; dat gebeurt niet.

Een TcpdfNotImplementedException in een periodieke strict-mode continuous integration (CI)-job (aanbevolen) is een echte bevinding. Het betekent dat een codepad afhankelijk is van een niet-ondersteunde TCPDF-parameter. Behandel het als een migratiewerkitem, niet als een instabiele test.

Levenscyclus en resourcebeheer

Het document bouwt zijn PDF-bytes lazy op bij de eerste uitvoeraanroep. Close() is optioneel; door het aan te roepen worden de bytes gecachet. Open() is een veilige no-op.
endPage() doet niets, omdat NextPDF de paginalevenscyclus beheert. Verwijder het uit hot loops; het voegt geen waarde toe.
Laat PHP de adapter tussen jobs via garbage collection opruimen. _destroy() reset de gecachete gegevens van de adapter, maar u hoeft het niet expliciet aan te roepen in normale workerloops.
Maak per document een nieuwe adapter aan. Hergebruik niet één adapter-instantie voor niet-gerelateerde documenten in een langlopende worker; de documentstatus is per instantie.

Prestatierichtlijnen

De adapter is een dunne delegatielaag; de engine bepaalt de kosten, niet de adapter.
Definieer legacy-constanten eenmalig bij het opstarten. LegacyDefaults::register() en LegacyBootstrap::enableAliases() zijn idempotent en beveiligd, waardoor herhaalde aanroepen goedkoop zijn. Constanten per request definiëren is verspilde moeite.
Geef in niet-browsercontexten de voorkeur aan Output(..., 'S') of 'F' boven 'I'/'D'. De inline/download-paden produceren framework-agnostische uitvoer die u in een worker doorgaans niet wilt.
Profileer bij generatie met hoog volume de engine, niet de adapter. Het budget per pagina voor de eigen overhead van de adapter is klein vergeleken met het renderen.

Gelijktijdigheid

Elke adapter-instantie is onafhankelijk en heeft zijn eigen documentstatus. Gelijktijdigheid op proces- of workerniveau is veilig wanneer elke werkeenheid zijn eigen adapter-instantie gebruikt.
De idempotentiebeveiligingen in LegacyBootstrap en LegacyDefaults gebruiken proceslokale statische status; ze zijn veilig onder de gangbare PHP-per-request/per-worker-modellen. Ze zijn niet bedoeld om muteerbare status tussen threads te delen.

Pre-productiechecklist

Strict-mode-audit voltooid; productie draait met strict mode uit.
Alle render-instappunten omhuld met try/catch voor RuntimeException (geen afhankelijkheid van die()).
Workers gebruiken Output(..., 'F') of 'S', nooit het inline-pad.
Legacy-constanten eenmalig gedefinieerd bij het opstarten, vóór de eerste constructie.
Er is een periodieke strict-mode-CI-job ingericht om regressies op te vangen.
Test-asserties op byteniveau zijn opnieuw als baseline vastgelegd (zie /integrations/tcpdf-compat/migration/).

Zie ook

/integrations/tcpdf-compat/security-and-operations/ — versleuteling, ondertekeningsstrategie en hardening
/integrations/tcpdf-compat/troubleshooting/ — productiefoutpatronen en oplossingen
/integrations/tcpdf-compat/configuration/ — strict mode en constantenhygiëne
/integrations/tcpdf-compat/migration/ — de audit die aan productie vooraf moet gaan