Panduan pengembang Artisan

Sekilas pandang

Paket Artisan memiliki dua tanggung jawab yang saling terkait: merender Hypertext Markup Language (HTML) melalui Chrome dan mengimpor halaman Portable Document Format (PDF) yang dihasilkan ke dalam dokumen NextPDF. Saat men-debug masalah, bedakan batas Chrome, pengurai, dan pengimpor.

Gunakan panduan ini saat menulis integrasi renderer, worker berumur panjang, diagnostik pengurai, atau pengujian untuk nextpdf/artisan.

Batas arsitektur

Lapisan	Dimiliki oleh	Tanggung jawab	Jangan tempatkan di sini
Aplikasi	Aplikasi	Mengotorisasi pembuatan HTML dan memilih konfigurasi renderer.	Manajemen proses peramban.
Kebijakan HTML	Aplikasi dan paket	Menolak HTML yang tidak aman atau berukuran berlebihan sebelum proses render.	Otorisasi tenant atau keputusan bisnis.
Perender Chrome	`nextpdf/artisan`	Merender HTML menjadi PDF mandiri yang dihasilkan Chrome.	Perbaikan PDF umum atau penyuntingan PDF arbitrer.
Pengurai/pengimpor	`nextpdf/artisan`	Mengurai PDF hasil render dan mengimpor satu halaman sebagai form XObject.	Validasi konformansi PDF secara penuh.
Mesin inti	`nextpdf/nextpdf`	Menempatkan objek form yang diimpor dan menulis dokumen akhir.	Siklus hidup Chrome DevTools Protocol (CDP).

Siklus hidup runtime

Tahap	Perilaku	Tindakan pengembang
Pembuatan konfigurasi	`ChromeRendererConfig` mendefinisikan biner, batas waktu, Cascading Style Sheets (CSS), ukuran masukan, dan perilaku sandbox.	Gunakan konfigurasi spesifik lingkungan, bukan tebakan runtime yang ditulis langsung di kode.
Pembuatan renderer	`ChromeHtmlRenderer` memiliki `BrowserPool`.	Gunakan kembali renderer di dalam worker, lalu tutup saat shutdown.
Validasi HTML	Kebijakan keamanan memeriksa ukuran dan membungkus dokumen dengan CSS standar.	Validasi otorisasi pemanggil sebelum tahap ini.
Cetak Chrome	CDP merender PDF mandiri.	Tetap blokir sumber daya eksternal, kecuali diizinkan oleh kebijakan yang telah ditinjau.
Penguraian PDF	`PdfReader::parse()` membaca data xref, halaman, objek, sumber daya, dan revisi.	Perlakukan kegagalan pengurai sebagai kegagalan render, kecuali tujuannya adalah diagnostik.
Impor halaman	`PageImporter::import()` mengekstrak konten halaman, media box, sumber daya, dan objek tersemat.	Impor halaman `0` kecuali alur kerja secara sengaja memilih halaman lain.

Struktur aplikasi yang disarankan

Path	Tujuan
`app/Pdf/Renderers/*`	Pembungkus aplikasi di sekitar `ChromeHtmlRenderer`.
`app/Pdf/Templates/*`	Perenderan templat HTML dan pemetaan data transfer object (DTO) ke tampilan.
`app/Pdf/Policies/*`	Kebijakan render untuk ukuran HTML, sumber daya, dan tenant.
`tests/Pdf/Renderer/*`	Pengujian smoke untuk renderer dengan fixture HTML kecil.
`tests/Pdf/Parser/*`	Fixture pengurai untuk keluaran Chrome yang diimpor.

Pisahkan proses render templat dari proses render peramban. Berikan HTML final dan lebar halaman yang sudah diketahui ke renderer.

<?php

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\PageImporter;
use NextPDF\Parser\PdfReader;

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig(
    renderTimeout: 30,
    maxHtmlSize: 1_000_000,
));

$result = $renderer->render($html, widthPt: 595.28);

$reader = new PdfReader($result->getPdfData());
$reader->parse();

$form = (new PageImporter())->import($reader);

Pola renderer

Buat satu renderer untuk setiap proses worker atau cakupan permintaan. Gunakan kembali untuk menghindari biaya startup Chrome yang berulang. Tutup secara eksplisit untuk mencegah kebocoran proses saat worker shutdown.

<?php

final class InvoiceChromeRenderer
{
    public function __construct(
        private readonly ChromeHtmlRenderer $renderer,
    ) {}

    public function renderInvoice(string $html): string
    {
        return $this->renderer
            ->render($html, widthPt: 595.28)
            ->getPdfData();
    }

    public function close(): void
    {
        $this->renderer->close();
    }
}

Pola diagnostik pengurai

Gunakan API pengurai saat keluaran Chrome gagal diimpor. Pastikan diagnostik tetap hanya-baca, dan hindari mengubah keadaan pengurai setelah impor berhasil.

Pertanyaan diagnostik	API yang digunakan	Sinyal yang diharapkan
Apakah berkas dapat diurai?	`PdfReader::parse()`	Melempar pengecualian untuk struktur PDF yang tidak valid.
Apakah halaman `0` ada?	`PdfReader::getPage(0)`	Mengembalikan `PdfObject`.
Apakah ada konten?	`PdfReader::getPageContentStream($page)`	Aliran konten yang tidak kosong.
Apakah sumber daya tersedia?	`PdfReader::getPageResources($page)`	Array kamus sumber daya.
Apakah ada revisi inkremental?	`PdfReader::getRevisionCount()`	Jumlahnya lebih dari satu.
Objek mana yang gagal?	`PdfTokenizer::getOffset()` dan konteks pengecualian pengurai.	Offset byte untuk reduksi fixture.

Titik perluasan

Titik perluasan	Gunakan untuk	Batasan
`ChromeRendererConfig::fromArray()`	Pemetaan konfigurasi framework.	Nilai opsional yang tidak dikenal atau salah ketik akan memakai nilai standar.
`HtmlSecurityPolicyInterface`	Kebijakan HTML pada lapisan pengurai.	Tidak menggantikan kendali transport, proses, atau otorisasi.
`LoggerInterface`	Diagnostik render dan peramban.	Jangan mencatat konten HTML secara default.
`BrowserPool`	Penggunaan ulang proses Chrome berumur panjang.	Harus ditutup saat worker shutdown.
`PageImporter`	Menyematkan halaman eksternal yang telah diurai.	Reader harus diurai terlebih dahulu.
Kelas pengurai	Diagnostik dan keluaran Chrome yang diimpor.	Bukan toolkit perbaikan PDF umum.

Alur kerja pengembangan

Reproduksi fragmen HTML dalam pengujian render minimal.
Validasi maxHtmlSize, CSS standar, dan jalur biner Chrome.
Lakukan render dengan lebar tetap dalam satuan poin.
Urai byte PDF yang dikembalikan dengan PdfReader::parse().
Impor halaman 0 kecuali alur kerja secara sengaja memilih halaman lain.
Tambahkan pengujian fixture untuk HTML terkecil yang mereproduksi setiap kegagalan.
Tutup renderer di hook shutdown worker.

Penanganan kegagalan

Kegagalan	Tempat penanganannya	Respons yang disarankan
Biner Chrome tidak ada	Pemeriksaan deployment dan alur konstruksi renderer.	Gagalkan kesiapan sebelum menerima lalu lintas render.
HTML berukuran berlebihan	Kebijakan HTML.	Tolak sebelum memulai Chrome.
Batas waktu peramban habis	Batas renderer.	Gagalkan render, lalu catat nama templat, ukuran, lebar, dan batas waktu.
Kegagalan pengurai	Batas impor.	Simpan fixture kecil yang telah disanitasi untuk debugging jika kebijakan mengizinkan.
Kebocoran proses peramban	Siklus hidup worker.	Tutup saat shutdown dan mulai ulang setelah mencapai jumlah render yang terkendali.

Nilai standar yang aman

Aspek	Standar	Kapan harus menggantinya
Batas waktu render	`30` detik.	Tingkatkan hanya untuk dokumen yang terukur dan dibatasi.
Ukuran HTML maksimum	`5,000,000` byte.	Turunkan untuk endpoint publik.
Sandbox	Diaktifkan.	Nonaktifkan hanya jika batasan kontainer mengharuskannya dan host terisolasi.
Tinggi	Otomatis saat `heightPt <= 0`.	Gunakan tinggi tetap untuk kontrak tata letak yang ketat.
Sumber daya eksternal	Diblokir oleh kebijakan renderer.	Izinkan hanya melalui kebijakan sumber daya yang telah ditinjau.

Daftar periksa pengujian

Pengujian render mencakup HTML dan CSS yang representatif.
Pengujian keamanan mencakup HTML berukuran berlebihan dan upaya mengakses sumber daya yang diblokir.
Pengujian impor memastikan objek form yang dikembalikan memiliki konten, media box, dan sumber daya.
Pengujian pengurai mencakup tabel referensi silang (xref), aliran xref, aliran objek, dan fixture untuk kasus yang rusak.
Pengujian worker memanggil close() dan memverifikasi tidak ada proses peramban yang tersisa.
Pengujian performa mencatat waktu render berdasarkan templat dan ukuran konten.