Mengapa engine PDF Anda seharusnya berada di PHP, bukan di sebuah sidecar

Spec: ISO/IEC 25010:2023, §3.7Spec: ISO 32000-2, §7

Sekilas

Ada dua tempat sebuah PDF dapat dibuat: di dalam proses PHP Anda, atau di suatu tempat lain yang harus Anda operasikan. NextPDF membuatnya di dalam. Halaman ini adalah argumen untuk pilihan itu — mengapa sebuah engine in-process biasanya merupakan default yang tepat, dan apa sebenarnya biaya pola “suatu tempat lain” itu begitu ia berada di produksi.

Ini adalah sudut arsitektur, bukan sudut framework. Bagaimana engine yang sama menjangkau Laravel, Symfony, CodeIgniter, dan kode standalone adalah cerita yang berbeda, dikisahkan di satu engine, setiap framework.

Mengapa ini penting

Sebuah fitur PDF jarang dimulai sebagai sebuah sistem yang Anda operasikan. Ia dimulai sebagai sebuah baris di sebuah controller: render invoice ini, kembalikan laporan itu. Pola sidecar mengubah baris itu menjadi infrastruktur. Untuk menggambar dokumennya, kini Anda menjalankan sesuatu yang kedua — sebuah biner eksternal, sebuah headless browser, sebuah microservice terpisah — dan segala yang dibutuhkan hal kedua itu menjadi masalah Anda juga: versinya, memorinya, kontainernya, jaringannya, mode kegagalannya, panggilan on-call-nya pada pukul 2 dini hari.

Biayanya tak terlihat pada demo dan tak terhindarkan di produksi. Sebuah engine dokumen yang hidup di dalam proses Anda tidak memiliki apa pun dari itu. Pertanyaannya bukan “dapatkah sebuah sidecar membuat sebuah PDF” — tentu saja bisa. Pertanyaannya adalah “apa yang Anda setujui untuk dioperasikan demi sampai ke sana, dan apakah Anda memang membutuhkannya.”

Versi singkatnya

In-process berarti tidak ada runtime kedua. NextPDF menggambar PDF di dalam worker PHP yang sama yang menangani permintaan. Tidak ada subproses untuk dijalankan, tidak ada layanan untuk di-deploy, dan tidak ada apa pun tambahan untuk dijaga tetap hidup.
Sebuah sidecar menambahkan permukaan operasional yang sebelumnya tidak Anda miliki. Sebuah browser yang dibundel atau biner eksternal membawa versinya sendiri, jejak keamanannya sendiri, dan kontainernya sendiri — yang kini semua Anda tambal dan pantau.
Batas proses adalah tempat segala sesuatu menjadi salah. Cold start, timeout, plumbing antarproses yang rapuh, dan data yang meninggalkan proses Anda adalah mode kegagalan yang sama sekali tidak dimiliki sebuah panggilan in-process.
In-process dapat diuji dan deterministik. Engine-nya adalah PHP bertipe yang dapat Anda unit-test, mock, dan nalar — bukan sebuah renderer buram yang hanya dapat Anda selidiki dengan menjalankannya dan melihat keluarannya.
Sebuah browser sungguhan tetap punya kegunaan nyata. Untuk rendering yang setia-piksel atas halaman web modern sembarang, sebuah headless browser adalah alat yang jujur — dan NextPDF dapat mendelegasikan ke satu secara sengaja. Ia adalah sebuah jahitan, bukan default.

Bagaimana NextPDF menanganinya

Tahan kedua arsitektur itu berdampingan. Jalur in-process adalah sebuah panggilan fungsi. Jalur sidecar adalah sebuah sistem terdistribusi dalam skala kecil — dan setiap anak panah di antara kotak-kotaknya adalah tempat yang gagal independen dari kode Anda.

In-process: call the enginewriteHtml() or the document API runs inside the current PHP worker — no subprocess, no socket.
In-process: receive PDF bytesThe engine returns native PDF content directly; nothing left the process.
Sidecar: serialize and shipMarkup or a request is marshalled out of your process to a binary, browser, or remote service.
Sidecar: cross the boundaryA process spawn or network hop — with a cold start, a timeout, and an IPC contract that can break.
Sidecar: run a second runtimeAn external renderer with its own version, memory profile, and security surface to operate and patch.
Sidecar: deserialize backMarshal the result back in and translate the renderer’s errors into yours.

Jalur in-process versus jalur sidecar. Secara in-process, PDF dihasilkan oleh sebuah panggilan bertipe di dalam worker PHP yang sama dan dikembalikan secara langsung. Jalur sidecar menambahkan sebuah langkah serialisasi, sebuah batas proses atau jaringan, sebuah runtime eksternal dengan versi dan jejaknya sendiri, dan sebuah langkah deserialisasi kembali — masing-masing sebuah mode kegagalan tersendiri yang tidak dimiliki panggilan in-process.

Tidak ada runtime kedua untuk dioperasikan. Pola sidecar adalah dua sistem yang mengenakan kostum satu fitur. Sebuah wkhtmltopdf yang dibundel, sebuah layanan Chromium headless, sebuah microservice render terpisah — masing-masing adalah sebuah runtime dengan kadensi rilisnya sendiri dan bug-nya sendiri. Anda mewarisi semuanya. Engine in-process dikirim sebagai sebuah dependensi Composer; ia dimutakhirkan dengan cara yang sama seperti setiap pustaka lain dalam composer.json Anda, tanpa daemon, image, atau socket yang ditambahkan ke deployment Anda.

Pergeseran versi dan permukaan keamanan yang lebih luas. Sebuah browser yang dibundel adalah sebuah basis kode yang besar dan bergerak cepat dengan aliran tetap penasihat keamanan. Pin ia dan ia membusuk; lacak ia dan ia bergolak. Cara mana pun, ia adalah seluruh platform web sebuah renderer yang duduk dalam rantai pasok Anda untuk memberi makan satu dokumen. Sebuah engine PHP in-process adalah sebuah pustaka kode yang terfokus yang dapat Anda baca; permukaan keamanannya adalah PHP yang sudah Anda jalankan, bukan sebuah platform kedua yang kini juga Anda jalankan.

Data tetap berada di dalam batas proses Anda. Ketika Anda shell out, konten dokumen — yang sering kali persis merupakan data sensitif yang justru menjadi alasan keberadaan sebuah PDF — melintasi sebuah batas. Ia ditulis ke sebuah pipe, sebuah argumen, sebuah berkas temp, atau sebuah socket jaringan menuju sebuah layanan. Setiap satu dari itu adalah tempat untuk bocor, untuk tercatat tanpa sengaja, atau untuk tertinggal. Secara in-process, datanya tidak pernah meninggalkan worker yang memilikinya. Radius ledakannya adalah satu proses, bukan sebuah armada.

Plumbing rapuh, cold start, dan timeout. Panggilan antarproses dan jaringan gagal dengan cara yang tidak bisa dialami sebuah panggilan fungsi: subproses yang tidak mulai, socket yang menggantung, timeout yang salah Anda tebak, cold start di bawah lonjakan trafik. Masing-masing membutuhkan kebijakan retry, sebuah circuit breaker, dan sebuah anggaran. Sebuah render in-process entah mengembalikan byte atau melempar sebuah exception bertipe yang Anda tangkap di baris berikutnya. Tidak ada state jaringan parsial untuk didamaikan.

Observabilitas dan pengujian menjadi lebih sulit melintasi batas. Sebuah kegagalan dalam sebuah sidecar tiba sebagai sebuah exit code, sebuah baris log terpotong, atau sebuah 500 dari sebuah layanan yang tidak Anda kendalikan. Mereproduksinya berarti mereproduksi seluruh lingkungan itu. Sebuah engine in-process dapat diamati dengan perkakas yang sudah Anda gunakan — sebuah stack trace, sebuah debugger, sebuah profiler — dan ia dapat diuji dengan cara yang sama seperti seluruh PHP Anda. Testabilitas itu adalah sebuah properti kualitas perangkat lunak bernama: ISO/IEC 25010 menempatkannya di bawah maintainability (Spec: ISO/IEC 25010:2023, §3.7), dan sebuah pustaka in-process memenuhinya jauh lebih langsung daripada sebuah renderer yang hanya dapat Anda jalankan dengan meluncurkannya.

PDF yang menjadi sasaran assert tes-tes itu adalah sebuah struktur yang terdefinisi, bukan sebuah kotak hitam. Sebuah berkas PDF memiliki tata letak objek dan berkas yang dispesifikasikan (Spec: ISO 32000-2, §7), dan sebuah engine in-process menghasilkan struktur itu dari kode yang dapat Anda baca — sehingga sebuah golden-file atau tes struktural memeriksa byte yang dihasilkan oleh sebuah fungsi yang diketahui, alih-alih keluaran dari sebuah program eksternal yang hanya dapat Anda amati.

Contoh praktis

Seluruh intinya muat dalam segelintir baris. Tidak ada klien, tidak ada base URL, tidak ada health check, dan tidak ada kebijakan retry — karena tidak ada sistem kedua.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// The engine runs inside this very process. No subprocess is spawned,
// no socket is opened, and the report data never leaves the worker.
$document = Document::createStandalone();
$document->setTitle('Quarterly Report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Quarterly Report</h1>
<p>Rendered <strong>in-process</strong> by PHP — no browser, no sidecar.</p>
HTML;

$document->writeHtml($html);

// PDF bytes are returned directly. There is no boundary to marshal across,
// so there is no timeout, cold start, or deserialization step to handle.
$bytes = $document->getPdfData();

Bandingkan bentuk dari versi sidecar — bukan kodenya, bentuk operasionalnya. Ia membutuhkan sebuah biner atau layanan untuk dipasang dan dapat dijangkau, sebuah permintaan yang diserialisasi dan dikirim, sebuah timeout yang dipilih, sebuah jalur kegagalan untuk saat renderer-nya dingin atau mati, dan hasilnya di-marshal kembali. Tidak satu pun dari itu ada di cuplikan di atas, karena tidak satu pun darinya ada ketika engine-nya adalah sebuah pustaka.

Kesalahpahaman umum

Asumsi yang sering muncul adalah bahwa rendering PDF “sungguhan” harus berarti sebuah browser, sehingga in-process pasti merupakan versi mainan. Itu memutar trade-off-nya secara terbalik. Sebuah browser adalah alat yang tepat ketika Anda membutuhkan rendering yang persis dan setia-piksel atas konten web modern sembarang. Ia adalah default yang salah untuk pekerjaan berbentuk-dokumen yang sebenarnya dilakukan kebanyakan tim — invoice, laporan, statement, kontrak — di mana tata letaknya diketahui, datanya milik Anda, dan kebenarannya diperiksa oleh sebuah validator, bukan oleh mata. Untuk pekerjaan itu, beban operasional sebuah sidecar tidak membelikan Anda apa pun yang belum diberikan engine in-process, dan menelan biaya segala yang ada di bagian-bagian di atas.

Kesalahpahaman cerminnya adalah yang dengan cermat tidak dilakukan halaman ini: mengklaim bahwa sebuah engine in-process me-render “seluruh web” seperti sebuah browser. Ia tidak, dan NextPDF tidak berpura-pura demikian. Pipeline HTML in-process-nya adalah sebuah subset yang selaras-spesifikasi yang berfokus pada tata letak dokumen, dengan batas-batas yang terdokumentasi — ruang lingkup jujurnya diuraikan di pipeline HTML. Ketika Anda benar-benar membutuhkan fidelitas browser penuh, itu adalah sebuah delegasi yang disengaja dan opt-in, bukan sebuah fallback senyap.

Batas dan ruang lingkup

In-process adalah default yang tepat. Ia bukan klaim universal bahwa sebuah subproses tidak pernah dibenarkan. Di mana sebuah dokumen benar-benar memerlukan rendering persis atas CSS modern sembarang yang tidak dicakup engine in-process, mendelegasikan ke sebuah headless browser adalah pilihan yang benar — dan NextPDF mendukung jalur itu secara sengaja, dengan akses jaringannya dibatasi, sebagai sebuah jahitan alih-alih default. Keduanya bukan rival; mereka adalah alat berbeda untuk pekerjaan berbeda.

Halaman ini memperdebatkan arsitekturnya, bukan sebuah matriks dukungan CSS. HTML dan CSS persis mana yang dicakup pipeline in-process didefinisikan oleh kode engine dan tes konformansinya, dan didokumentasikan bersama pipeline itu — bukan dijanjikan di sini. “In-process” menggambarkan jalur rendering default; ia bukan klaim bahwa setiap jalur yang mungkin menghindari sebuah subproses.

Permukaan kapabilitasnya tetap sederhana: engine in-process adalah Core, dan jalur delegasi-browser adalah sebuah ekstensi opsional, independen dari edisi.

Where the PDF is rendered — edition availability
Edition	Availability
Core	Core renders PDF in-process in PHP — no subprocess, binary, or sidecar by default.
Pro	The headless-browser delegation path is an optional add-on extension, independent of edition tier.
Enterprise	The headless-browser delegation path is an optional add-on extension, independent of edition tier.

Dokumen terkait

Pipeline HTML — ruang lingkup jujur dari engine in-process, dan persis kapan mendelegasikan ke sebuah browser adalah tepat.
Satu engine, setiap framework — sumbu pelengkapnya: bagaimana engine in-process yang sama menjangkau setiap framework PHP tanpa sebuah pustaka berbeda per stack.
Mengoperasikan NextPDF di produksi — seperti apa menjalankan sebuah engine in-process dari hari ke hari, tanpa runtime tambahan untuk dioperasikan.
Memori dan streaming — bagaimana engine menjaga generasi in-process tetap terbatas di bawah beban.

Glosarium

Generasi in-process — menghasilkan PDF di dalam worker PHP yang sama yang menangani permintaan, tanpa subproses, socket, atau layanan eksternal.
Sidecar — sebuah runtime terpisah yang berjalan berdampingan dengan aplikasi Anda untuk melakukan satu pekerjaan; di sini, sebuah biner eksternal, headless browser, atau microservice yang me-render PDF di luar proses Anda.
Cold start — latensi dan lonjakan sumber daya yang terjadi ketika sebuah subproses atau layanan harus dimulai dari nol sebelum ia dapat melayani permintaan pertama.
IPC — inter-process communication: pipe, socket, berkas temp, atau panggilan jaringan yang digunakan untuk mengoper data ke dan dari sebuah proses terpisah, dan sumber berulang dari kegagalan yang rapuh dan sulit di-debug.
Jahitan delegasi-browser — jalur opsional dan opt-in yang menyerahkan sebuah render ke sebuah headless browser demi fidelitas yang persis, dengan akses jaringan subresource diblokir; sebuah pilihan yang disengaja, bukan default.