Gambaran Umum NextPDF Artisan

Sekilas pandang

NextPDF Artisan adalah jembatan Chrome untuk NextPDF. Jembatan ini mengirim fragmen Hypertext Markup Language (HTML) ke proses Chrome headless melalui Chrome DevTools Protocol (CDP), menangkap keluaran printToPDF, lalu menyematkan hasilnya ke dokumen Portable Document Format (PDF) target sebagai Form XObject. Teks yang disematkan tetap dapat dipilih dan dicari.

Ikhtisar konseptual

Paket Artisan (nextpdf/artisan) memperluas mesin NextPDF sumber terbuka dengan renderer yang mendelegasikan tata letak ke Chrome. Alur HTML bawaan NextPDF sudah mencakup subset Cascading Style Sheets (CSS) yang luas. Gunakan jembatan Artisan untuk dokumen yang memerlukan tata letak setara Chrome, termasuk CSS flexbox dan grid, fon web kustom yang dimuat dari sumber data Uniform Resource Identifier (URI), serta selektor yang rumit, sambil tetap menghasilkan teks vektor alih-alih tangkapan layar yang dirasterkan.

Jembatan ini berjalan sebagai alur komponen-komponen kecil yang masing-masing memiliki satu tujuan. ChromeHtmlRenderer mengorkestrasi sebuah proses render. ChromeSecurityPolicy memvalidasi masukan dan membungkusnya dalam dokumen HTML yang terkunci ketat. BrowserPool mengelola siklus hidup proses Chrome. ViewportCalculator memetakan titik PDF ke piksel CSS. Pembaca NextPDF\Parser mengurai keluaran Chrome, dan PageImporter mengubahnya menjadi Form XObject. Setiap komponen bersifat final, diinjeksikan melalui konstruktor, dan memiliki tipe eksplisit untuk PHPStan level 10.

Jembatan ini terikat pada dependensi eksternal. Jembatan ini memerlukan pustaka chrome-php/chrome (^1.15) dan biner Chrome atau Chromium yang dapat dijangkau oleh proses PHP. Keduanya tidak disertakan dalam paket. Ketika pustaka tidak tersedia, jembatan akan melempar ChromeNotAvailableException alih-alih gagal secara diam-diam; lihat /integrations/artisan/failure-modes/ pada halaman /integrations/artisan/troubleshooting/.

Perender tidak pernah mengirim konten ke Chrome sampai masukan lolos ChromeSecurityPolicy::validate(). Dokumen yang diterima Chrome selalu dibungkus dengan Content Security Policy (CSP) yang ketat melalui header Content-Security-Policy dan pemblokiran jaringan CDP sebagai lapisan pertahanan tambahan. Karena jembatan ini memproses HTML yang berpotensi tidak tepercaya, halaman /integrations/artisan/security-and-operations/ mendokumentasikan model transport dan isolasinya, bukan merangkumnya di sini.

Halaman ini menjelaskan perilaku paket sebagaimana dirilis dan diverifikasi terhadap src/Artisan/ serta suite tests/Unit/Artisan/. Ini bukan klaim kesetaraan piksel demi piksel dengan peramban Chrome interaktif: animasi ditangkap pada frame terakhirnya, tata letak tidak bergantung pada JavaScript, dan hanya halaman Chrome pertama yang diimpor.

Arsitektur

Diagram

Tanggung jawab komponen

Komponen	Tanggung jawab	Sumber
ChromeHtmlRenderer	Mengorkestrasi satu proses render; mengembalikan ChromeRenderResult	src/Artisan/ChromeHtmlRenderer.php
ChromeRendererConfig	Objek nilai konfigurasi yang tidak dapat diubah	src/Artisan/ChromeRendererConfig.php
ChromeSecurityPolicy	Validasi masukan + pembungkus HTML yang aman	src/Artisan/ChromeSecurityPolicy.php
BrowserPool	Siklus hidup proses Chrome dan kebijakan mulai ulang	src/Artisan/BrowserPool.php
ViewportCalculator	Konversi 72 pt/inch ↔ 96 px/inch	src/Artisan/ViewportCalculator.php
ChromeRenderResult	Keluaran render bertipe (ChromeRenderResultInterface)	src/Artisan/ChromeRenderResult.php
PageImporter	Halaman Chrome yang diurai → ImportedFormXObject	src/Artisan/PageImporter.php
EInvoiceServiceFactory	Factory tanpa kontainer untuk kontrak e-invoice Premium	src/Artisan/EInvoiceServiceFactory.php

Kasus tepi & hal yang perlu diperhatikan

• Riwayat versi. Artefak Composer yang dipublikasikan diberi tag v0.1.0. Docblock sumber memuat @since 1.7.0 (jembatan Chrome) dan @since 1.1.0 (factory e-invoice), keduanya diwarisi dari garis versi nextpdf/core sebelum penggantian nama; paket ini diganti namanya menjadi nextpdf/artisan pada entri CHANGELOG 2.0.0. Perlakukan tag Composer sebagai sumber otoritatif untuk versi instalasi, dan perlakukan penanda @since sebagai riwayat versi mesin.
• Hanya halaman pertama. PageImporter::import() secara default menggunakan indeks halaman 0. Konten yang meluap ke halaman Chrome kedua akan terpotong kecuali Anda menetapkan tinggi yang eksplisit, sebagaimana dibahas pada halaman /integrations/artisan/production-usage/.
• Tanpa kontainer dependency injection (DI). Artisan tidak menggunakan kontainer. EInvoiceServiceFactory memberi lingkungan layanan tanpa kontainer cara yang konsisten untuk menginstansiasi layanan; lihat /integrations/artisan/boot-and-discovery/.

Performa

Setiap proses render menanggung biaya pemuatan halaman Chrome dan printToPDF sekali per pemanggilan. BrowserPool menjaga proses Chrome tetap hidup di antara proses render dan memulainya ulang setiap 100 render untuk membatasi pertumbuhan memori. Pekerjaan tata letak Chrome, bukan jembatan itu sendiri, yang mendominasi perilaku Big-O. Untuk anggaran terukur bagi alur acuan halaman ini, lihat performance_budget di frontmatter dan halaman /integrations/artisan/production-usage/.

Catatan keamanan

Jembatan ini merender HTML yang berpotensi tidak tepercaya di dalam Chrome. Masukan divalidasi berdasarkan ukuran dan konten sebelum Chrome melihatnya. Dokumen yang dibungkus menyertakan default-src 'none'. Pemblokiran pada tingkat CDP menghentikan setiap permintaan subsumber daya. Model transport dan isolasi yang lengkap, termasuk batasan eksplisit flag sandbox Chrome, tersedia pada halaman /integrations/artisan/security-and-operations/. Jangan perlakukan bagian ini sebagai postur keamanan yang lengkap.

Konteks komersial

Jembatan sumber terbuka merender HTML menjadi PDF. Tingkatan Premium menambahkan penyematan e-invoice yang patuh (Pro) dan validasi (Enterprise) di atas dokumen yang telah dirender. Ketika tingkatan tersebut tidak diinstal, EInvoiceServiceFactory mengembalikan null, sehingga alur sumber terbuka tetap berfungsi penuh tanpanya.

Lihat juga

• /integrations/artisan/install/
• /integrations/artisan/configuration/
• /integrations/artisan/quickstart/
• /integrations/artisan/chrome-renderer-setup/
• /integrations/artisan/security-and-operations/
• /integrations/artisan/production-usage/