Konfigurasi compat-legacy

Gambaran umum

Adapter ini menyediakan tiga area konfigurasi:

Mode ketat — sakelar audit yang mengubah parameter yang hilang secara diam-diam menjadi eksepsi. Secara bawaan, mode ini nonaktif.
Konstanta lawas — konstanta TCPDF K_* / PDF_*, yang didefinisikan otomatis dengan nilai standar 6.2.13 agar kode lawas yang membacanya tetap berfungsi.
AdaptationConfig — objek konfigurasi modern dan imutabel yang menggantikan konfigurasi berbasis konstanta.

Anda tetap mengonfigurasi sebagian besar pengaturan dokumen melalui metode TCPDF yang sudah Anda gunakan (SetMargins(), SetFont(), dan seterusnya). Bagian di bawah ini hanya membahas hal-hal yang khusus untuk lapisan kompatibilitas.

Mode ketat

Mode ketat adalah pengaturan kunci dalam migrasi. Mode ini tidak mengubah keluaran yang dirender. Mode ini mengontrol apakah panggilan yang tidak dapat mereproduksi perilaku TCPDF gagal secara eksplisit atau terdegradasi secara diam-diam.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();

$pdf->setStrictMode(true);   // audit: throw on silent parameter loss
$isOn = $pdf->isStrictMode(); // true
$pdf->setStrictMode(false);  // back to backward-compatible default

Perilaku ini ditegaskan oleh tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php:

Mode	Metode abai-diam yang dipanggil	Hasil
Nonaktif (bawaan)	misalnya `Image()` dengan parameter tambahan	Berjalan; parameter yang diabaikan tidak berpengaruh
Aktif	panggilan yang sama	Melempar `TcpdfNotImplementedException` yang menyebutkan parameter yang diabaikan
Aktif	metode abai-diam yang dipanggil hanya dengan parameter yang didukung	Tidak melempar (misalnya `SetProtection([], 'u', 'o', 0, [])`)

Mode ketat bersifat aditif. Ketika sebuah metode mendukung suatu parameter, delegasi tetap berjalan; mode ketat hanya menambahkan pengaman eksepsi untuk parameter yang dibuang. Gunakan mode ini pada tugas continuous integration (CI) khusus atau pemeriksaan audit sekali jalan, bukan di lingkungan produksi. Hal ini mengikuti prinsip gagal-secara-eksplisit dalam penanganan kesalahan Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) 5.0 (klausa reference_id tercatat dalam sidecar RAG): pemanggil harus dapat mengetahui ketika maksudnya tidak terpenuhi.

Jangan kirimkan kode produksi dengan mode ketat aktif. Parameter yang diabaikan secara diam-diam adalah masalah pengalaman pengembang, bukan kesalahan saat runtime, dan eksepsi dalam jalur render produksi lebih buruk daripada keluaran yang terdegradasi. Audit, perbaiki, lalu nonaktifkan — lihat /integrations/tcpdf-compat/migration/.

Konstanta TCPDF lawas

TCPDF lawas membaca konfigurasi dari konstanta K_* dan PDF_*. Adapter mendefinisikannya secara otomatis pada saat konstruksi hanya jika belum terdefinisi, menggunakan nilai standar TCPDF 6.2.13. Jika aplikasi Anda sudah mendefinisikan suatu konstanta (misalnya, K_PATH_FONTS kustom), nilai Anda dipertahankan.

Berikut beberapa nilai standar terpilih (daftar lengkap: src/Compat/Tcpdf/Config/LegacyDefaults.php):

Konstanta	Nilai standar	Catatan
`PDF_PAGE_FORMAT`	`A4`
`PDF_PAGE_ORIENTATION`	`P`
`PDF_UNIT`	`mm`
`PDF_MARGIN_LEFT` / `RIGHT`	`15`	satuan pengguna
`PDF_MARGIN_TOP`	`27`	satuan pengguna
`PDF_MARGIN_BOTTOM`	`25`	satuan pengguna
`PDF_FONT_NAME_MAIN`	`helvetica`
`PDF_FONT_SIZE_MAIN`	`10`
`K_CELL_HEIGHT_RATIO`	`1.25`
`K_TCPDF_CALLS_IN_HTML`	`false`	diperkuat — selalu false; markup tidak dapat memicu eksekusi PHP
`K_TCPDF_THROW_EXCEPTION_ERROR`	`true`	diperkuat — `Error()` selalu melempar; tidak pernah `die()`
`K_TIMEZONE`	`UTC`

Dua di antaranya sengaja ditetapkan demi keamanan dan tidak dapat dilonggarkan melalui konfigurasi: K_TCPDF_CALLS_IN_HTML selalu false, dan K_TCPDF_THROW_EXCEPTION_ERROR secara efektif selalu true. Jika kode lawas bergantung pada salah satu perilaku lama yang tidak aman tersebut, kode itu harus diubah — lihat /integrations/tcpdf-compat/security-and-operations/.

Definisikan konstanta kustom sebelum konstruksi adapter pertama, biasanya pada bootstrap aplikasi Anda:

<?php

declare(strict_types=1);

// Define BEFORE constructing the adapter; the adapter will not override it.
define('PDF_CREATOR', 'My Application');
define('PDF_AUTHOR', 'My Application');

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
// Creator and Author are seeded from your constants.

Objek AdaptationConfig modern

Jika Anda tidak ingin bergantung pada konstanta global, gunakan objek nilai konfigurasi yang imutabel, NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Objek ini bersifat final readonly, dan setiap bidang menggunakan nilai TCPDF 6.2.13 secara bawaan. Anda dapat membuatnya hanya dengan bidang yang ingin Anda ubah.

Anda juga dapat membuatnya dari konstanta lawas apa pun yang saat ini terdefinisi:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Config\AdaptationConfig;

// Snapshot the currently-defined legacy constants into an object:
$config = AdaptationConfig::fromLegacyConstants();

echo $config->pageFormat;   // 'A4' unless a constant overrides it
echo $config->fontNameMain; // 'helvetica'
echo $config->marginLeft;   // 15.0

AdaptationConfig adalah target migrasi untuk konfigurasi. Saat Anda memindahkan lokasi pemanggilan ke API modern, ganti pencarian konstanta dengan bidang AdaptationConfig yang eksplisit. Dengan begitu, konfigurasi tetap bertipe dan lokal, bukan global.

Urutan resolusi konfigurasi

Saat adapter membangun dokumen, konfigurasi diselesaikan dalam urutan berikut. Langkah berikutnya tidak menimpa langkah sebelumnya:

Argumen konstruktor (orientation, unit, format, …) — prioritas tertinggi untuk nilai yang dicakupnya.
Konstanta lawas yang sebelumnya sudah didefinisikan oleh aplikasi.
Konstanta standar TCPDF 6.2.13, yang didefinisikan otomatis oleh LegacyDefaults untuk konstanta apa pun yang belum terdefinisi.

Argumen konstruktor unicode, encoding, dan diskcache diterima demi kompatibilitas tanda tangan dan tidak berpengaruh. NextPDF selalu Unicode dan UTF-8, serta tidak memiliki cache halaman di disk. Flag konstruktor pdfa juga diterima, tetapi konformitas pengarsipan PDF/A memerlukan edisi komersial (lihat /integrations/tcpdf-compat/security-and-operations/).

Lihat juga

src/Compat/Tcpdf/Config/LegacyDefaults.php — nilai standar konstanta yang otoritatif
src/Compat/Tcpdf/Config/AdaptationConfig.php — objek konfigurasi modern
/integrations/tcpdf-compat/migration/ — memindahkan konfigurasi dari konstanta global
/integrations/tcpdf-compat/security-and-operations/ — dua flag yang diperkuat dan tidak dapat dikonfigurasi