Menjalankan compat-legacy di lingkungan produksi

Sekilas pandang

Adapter ini aman dijalankan di handler Hypertext Transfer Protocol (HTTP), pekerja antrean, dan proses yang berjalan lama. Adapter ini lebih aman daripada TCPDF lawas 6.2.13 karena menghilangkan dua risiko produksi yang paling mungkin Anda alami: output langsung ke buffer dan die() saat terjadi galat. Gunakan halaman ini sebagai panduan untuk mengoperasikannya dengan benar.

Sebelum masuk produksi, selesaikan audit mode ketat di /integrations/tcpdf-compat/migration/ dan jalankan dengan mode ketat mati.

Penanganan output di pekerja dan handler

TCPDF lawas Output() menulis langsung ke buffer output yang aktif. Hal ini dapat merusak respons di framework HTTP dan menggagalkan pekerja antrean. Sebagai gantinya, adapter merutekan output melalui jembatan tujuan yang aman.

Pilih tujuan yang sesuai dengan pemanggilnya:

Konteks	Tujuan	Alasan
Pekerja antrean yang menulis ke penyimpanan	`Output($path, 'F')`	Menulis berkas dan mengembalikan string kosong. Tidak berinteraksi dengan buffer.
Hasilkan lalu attach/upload	`Output($name, 'S')`	Mengembalikan byte Portable Document Format (PDF); Anda yang menentukan ke mana byte itu diarahkan.
Lampiran email	`Output($name, 'E')`	Mengembalikan body Multipurpose Internet Mail Extensions (MIME) base64 dengan `Content-Type: application/pdf`.
Respons HTTP yang Anda kendalikan	`Output($name, 'S')`	Mendapatkan byte, lalu Anda menyetel sendiri header dan body respons.

<?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;
}

Di handler HTTP, lebih baik gunakan 'S' dan setel sendiri header-nya:

<?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;

Penanganan kegagalan

Error() melempar RuntimeException dan tidak pernah memanggil die(). Inilah perubahan operasional terpenting dari TCPDF lawas.

Bungkus setiap titik masuk render dalam try/catch.
Petakan exception ke kontrak galat aplikasi Anda, seperti HTTP 5xx, job gagal, percobaan ulang, atau dead-letter.
Jangan berasumsi bahwa proses berakhir saat terjadi kegagalan render; proses tidak berakhir.

TcpdfNotImplementedException dalam job mode ketat berkala di continuous integration (CI) (disarankan) menandakan temuan nyata. Artinya, ada jalur kode yang mengandalkan parameter TCPDF yang tidak didukung. Perlakukan sebagai item pekerjaan migrasi, bukan pengujian yang tidak stabil.

Siklus hidup dan penanganan sumber daya

Dokumen membangun byte PDF-nya secara lazy pada panggilan output pertama. Close() bersifat opsional; memanggilnya akan menyimpan byte tersebut di cache. Open() adalah no-op yang aman.
endPage() tidak melakukan apa pun karena NextPDF mengelola siklus hidup halaman. Hapus dari hot loop; ia tidak memberikan nilai tambah.
Biarkan PHP melakukan garbage collection pada adapter di antara job. _destroy() mengatur ulang data cache adapter, tetapi Anda tidak perlu memanggilnya secara eksplisit dalam loop pekerja normal.
Buat adapter baru untuk setiap dokumen. Jangan gunakan kembali satu instance adapter untuk dokumen-dokumen yang tidak berkaitan di dalam pekerja yang berjalan lama; status dokumen bersifat per-instance.

Panduan performa

Adapter adalah lapisan delegasi tipis; biaya didominasi oleh mesin, bukan adapter.
Definisikan konstanta lawas sekali saja saat boot. LegacyDefaults::register() dan LegacyBootstrap::enableAliases() bersifat idempoten dan dilindungi guard, sehingga biaya panggilan berulang kecil. Mendefinisikan konstanta per permintaan membuang-buang kerja.
Lebih baik gunakan Output(..., 'S') atau 'F' daripada 'I'/'D' di konteks non-peramban. Jalur inline/download menghasilkan output yang agnostik terhadap framework, yang biasanya tidak Anda inginkan di dalam pekerja.
Untuk pembuatan bervolume tinggi, lakukan profiling pada mesinnya, bukan adapter-nya. Anggaran per halaman untuk overhead adapter sendiri kecil dibandingkan dengan proses rendering.

Konkurensi

Setiap instance adapter bersifat independen dan menyimpan status dokumennya sendiri. Konkurensi di level proses atau pekerja aman ketika setiap unit kerja menggunakan instance adapter-nya sendiri.
Penjaga idempotensi di LegacyBootstrap dan LegacyDefaults menggunakan status statis lokal-proses; keduanya aman pada model PHP per-request/per-worker yang umum. Keduanya tidak dirancang untuk berbagi status mutable di antara thread.

Daftar periksa praproduksi

Audit mode ketat selesai; produksi berjalan dengan mode ketat mati.
Semua titik masuk render dibungkus dalam try/catch untuk RuntimeException (tanpa mengandalkan die()).
Pekerja menggunakan Output(..., 'F') atau 'S', jangan pernah jalur inline.
Konstanta lawas didefinisikan sekali saja saat boot, sebelum konstruksi pertama.
Job CI mode ketat berkala sudah tersedia untuk menangkap regresi.
Asersi pengujian tingkat byte telah di-baseline ulang (lihat /integrations/tcpdf-compat/migration/).

Lihat juga

/integrations/tcpdf-compat/security-and-operations/ — enkripsi, postur penandatanganan, dan pengerasan
/integrations/tcpdf-compat/troubleshooting/ — pola kegagalan produksi dan perbaikannya
/integrations/tcpdf-compat/configuration/ — mode ketat dan kebersihan konstanta
/integrations/tcpdf-compat/migration/ — audit yang harus mendahului produksi