Panduan pengembang untuk kompatibilitas TCPDF

Sekilas

Adapter kompatibilitas merupakan lapisan migrasi. Adapter ini membuat perilaku lama tetap terlihat, bukan menyembunyikannya. Gunakan adapter ini untuk menjaga aplikasi Anda tetap berjalan saat memindahkan jalur bernilai tinggi ke API NextPDF native.

Gunakan panduan ini saat Anda memelihara kode lama bergaya TCPDF, menambahkan cakupan adapter, atau merencanakan migrasi bertahap ke API NextPDF native.

Batasan arsitektur

Lapisan	Dimiliki oleh	Tanggung jawab	Jangan letakkan di sini
Aplikasi lama	Aplikasi	Menjaga panggilan bergaya TCPDF yang ada tetap berjalan selama migrasi.	Fitur PDF baru yang sebaiknya dibangun dengan API NextPDF native.
Cangkang adapter	`nextpdf/compat-legacy`	Mengekspos kelas bergaya `TCPDF` dan status kompatibilitas bersama.	Famili metode besar atau logika konversi.
Trait concern	`nextpdf/compat-legacy`	Mengelompokkan famili metode lama: teks, fon, gambar, keamanan, formulir, halaman.	Kebijakan keluaran yang berlaku lintas famili.
Kelas jembatan	`nextpdf/compat-legacy`	Mengonversi argumen, tujuan, warna, satuan, dan format lama.	Perilaku khusus bisnis.
Mesin inti	`nextpdf/nextpdf`	Membuat dokumen native.	Jaminan kompatibilitas lama.

Siklus hidup runtime

Tahap	Perilaku	Tindakan pengembang
Bootstrap	Bootstrap lama opsional mengekspos nama kompatibilitas.	Gunakan hanya di bagian kode lama yang mengharapkan simbol TCPDF.
Konstruksi	Adapter memetakan argumen konstruktor lama ke konfigurasi dokumen inti.	Pertahankan masukan konstruktor tetap stabil selama migrasi.
Panggilan metode	Metode yang didukung dipetakan ke perilaku NextPDF melalui concern dan jembatan.	Periksa cakupan metode sebelum berasumsi bahwa perilakunya setara.
Fitur yang tidak didukung	Adapter melempar pengecualian kompatibilitas eksplisit untuk perilaku yang tidak didukung.	Ganti panggilan tersebut atau isolasikan di balik kode aplikasi.
Keluaran	Jembatan keluaran memetakan perilaku tujuan lama ke keluaran NextPDF.	Validasi nama berkas dan akar penyimpanan.

Inventarisasi migrasi

Mulailah dengan menginventarisasi setiap panggilan metode TCPDF di aplikasi Anda. Klasifikasikan setiap panggilan sebelum mengubah perilakunya.

Klasifikasi	Makna	Tindakan
Metode adapter yang didukung	Metode tersebut didokumentasikan sebagai metode yang didukung dan memiliki pengujian.	Pertahankan untuk sementara, lalu migrasikan saat Anda menyentuh area tersebut.
Metode adapter parsial	Metode tersebut ada, tetapi perilakunya tidak sepenuhnya cocok dengan TCPDF lama.	Tambahkan pengujian berbasis fixture dan validasi keluaran secara manual.
Metode tidak didukung secara eksplisit	Adapter melempar pengecualian kompatibilitas.	Ganti dengan NextPDF native atau hapus fitur tersebut.
Pembungkus khusus bisnis	Aplikasi sudah membungkus panggilan TCPDF tersebut.	Migrasikan bagian internal pembungkus terlebih dahulu.
Panggilan yang sensitif terhadap kepatuhan	Tanda tangan, enkripsi, penandaan, PDF/A, aksesibilitas, atau alur kerja faktur.	Migrasikan ke API NextPDF native dengan verifikasi khusus.

Pola kontribusi adapter

Tambahkan dukungan kompatibilitas pada famili metode terkecil yang memuat perilaku tersebut.

Jenis perubahan	Tempat mengimplementasikan	Pengujian yang diperlukan
Metode keluaran teks	`Concerns\AdaptsTextOutput` atau concern fon.	Fixture lama ditambah asersi keluaran native.
Metode halaman atau margin	Concern halaman, pemosisian, atau margin.	Pengujian konversi koordinat dan status halaman.
Metode gambar atau penggambaran	Concern gambar, penggambaran, warna, atau gradien.	Pengujian validasi masukan dan keluaran visual/structural.
Tujuan keluaran	`OutputBridge`.	Pengujian pemetaan tujuan dan jalur tidak aman.
Fitur yang tidak didukung	Pabrik pengecualian atau tabel cakupan metode.	Pengujian jenis pengecualian serta pesannya.

Jangan letakkan metode besar langsung di cangkang adapter jika trait concern sudah memiliki famili tersebut.

Pola migrasi native

Gunakan adapter untuk menstabilkan kode lama, lalu pindahkan alur kerja yang stabil ke API native.

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

Perlakukan migrasi sebagai rangkaian perpindahan perilaku kecil. Satu halaman masih dapat menggunakan adapter, sementara satu bagian berisiko tinggi dipindahkan ke API native.

Titik ekstensi

Titik ekstensi	Gunakan untuk	Batasan
`AdaptationConfig`	Mengontrol perilaku adapter selama migrasi.	Pastikan nilai standar tetap eksplisit dan ditinjau.
Trait concern	Mengelompokkan famili metode seperti teks, formulir, gambar, atau keamanan.	Tambahkan metode ke concern yang sesuai, bukan langsung ke cangkang adapter.
Kelas jembatan	Mengonversi bentuk argumen lama menjadi nilai inti.	Lindungi perilaku jembatan dengan pengujian migrasi.
`CompatAdapterInterface`	Abstraksi tingkat adapter untuk perkakas.	Jangan gunakan sebagai pengganti kontrak inti native dalam kode baru.
Tabel cakupan metode	Catatan dukungan yang ditujukan untuk pengembang.	Perbarui saat status dukungan berubah.

Alur kerja migrasi

Pasang adapter dan jalankan rangkaian pengujian lama tanpa perubahan.
Buka cakupan metode dan klasifikasikan setiap metode yang dipanggil.
Ganti metode yang tidak didukung terlebih dahulu.
Pindahkan jalur bervolume tinggi atau sensitif terhadap kepatuhan ke API inti native.
Tambahkan cakupan fixture untuk setiap famili metode yang dimigrasikan.
Hapus alias bootstrap saat tidak ada titik masuk aplikasi yang bergantung padanya.

Penanganan kegagalan

Kegagalan	Tempat penanganan yang tepat	Respons yang disarankan
Metode tidak didukung	Pengecualian adapter.	Ganti panggilan tersebut atau isolasikan di balik adapter aplikasi.
Kesetaraan tata letak parsial	Pengujian migrasi dan tinjauan visual.	Dokumentasikan perbedaan yang dapat diterima sebelum peluncuran.
Tujuan keluaran tidak aman	`OutputBridge` dan kebijakan penyimpanan aplikasi.	Tolak jalur yang tidak aman dan utamakan API keluaran native.
Ketidakcocokan fitur keamanan	Rencana migrasi native.	Jangan merilis perilaku khusus kompatibilitas untuk keluaran yang diatur regulasi.
Tabrakan alias bootstrap	Bootstrap aplikasi.	Hapus alias global atau batasi cakupannya pada titik masuk lama.

Nilai standar yang aman

Concern	Standar	Kapan perlu menimpa
Metode yang tidak didukung	Lemparkan pengecualian eksplisit.	Jangan melemahkannya di lingkungan produksi.
Nilai standar lama	Dipusatkan di `LegacyDefaults`.	Timpa hanya untuk perilaku migrasi yang diketahui.
Pemetaan keluaran	Melalui `OutputBridge`.	Gunakan API keluaran native setelah migrasi.
Sumber cakupan	Halaman cakupan metode dan pengujian.	Jalankan kembali pemeriksaan cakupan setelah setiap peningkatan adapter.
Mode ketat	Tetap aktif selama audit migrasi.	Nonaktifkan hanya untuk jendela kompatibilitas lama yang terdokumentasi.

Daftar periksa pengujian

Pertahankan fixture lama untuk setiap famili metode yang dimigrasikan.
Tambahkan satu pengujian NextPDF native sebelum Anda mengganti metode lama.
Pastikan metode yang tidak didukung melemparkan pengecualian yang terdokumentasi.
Bandingkan struktur keluaran ketika kesetaraan byte persis bukan target migrasi yang realistis.
Jalankan pemeriksaan cakupan metode setelah Anda menambahkan atau mengubah metode adapter.
Tambahkan pengujian jalur penyimpanan untuk setiap tujuan keluaran yang digunakan kode lama.