Panduan keputusan integrasi

Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x162 ISO/IEC/IEEE 26514:2022 §3.x162 Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 Evidence ¶ Editorial Evidence: Editorial

Sekilas

Ekosistem NextPDF terdiri dari mesin inti kecil dan sekumpulan paket terfokus: jembatan framework, dua renderer HTML, satu renderer edge, dan satu server eksekusi. Halaman ini memetakan kasus penggunaan nyata ke paket yang sesuai, berdasarkan apa yang benar-benar disediakan setiap paket. Pilihan tetap di tangan Anda, berlandaskan bukti, bukan sekadar implikasi dokumentasi.

Mengapa ini penting

Memilih integrasi yang salah itu mahal dengan cara yang tidak langsung terlihat. Jika Anda memilih renderer peramban jarak jauh padahal mesin in-process sudah dapat merender dokumen dengan benar, Anda menambahkan satu lompatan jaringan dan dependensi ketersediaan ke setiap PDF. Jika Anda memilih mesin in-process untuk dokumen yang benar-benar membutuhkan mesin tata letak peramban penuh, Anda akan mendapatkan berkas yang keliru dengan cara yang sulit terlihat. Paket yang Anda adopsi membentuk latensi, mode kegagalan, dan permukaan operasional, sehingga keputusan ini layak dibuat secara eksplisit.

Ringkasan singkat

• Mulailah dengan mesin inti. Yang lain hanya tambahan. Jika mesin in-process merender dokumen Anda dengan benar, Anda sama sekali tidak memerlukan paket renderer.
• Jembatan framework mengikuti framework Anda, bukan dokumen Anda. Integrasi Laravel, Symfony, dan CodeIgniter ada agar Anda memperoleh facade atau factory, respons PDF, pembuatan berbasis antrean, dan penemuan otomatis — semuanya tidak mengubah apa yang dapat dirender oleh mesin.
• Gunakan renderer hanya ketika fidelitas CSS membutuhkan peramban. Artisan (Chrome lokal) dan Cloudflare (peramban edge) ada justru untuk itu; Gotenberg ada untuk membawa masuk dokumen Office.
• Gunakan Connect ketika pemanggilnya berupa layanan atau agen AI, bukan panggilan PHP. Connect mengekspos mesin melalui MCP, REST, dan gRPC dengan gerbang persetujuan manusia untuk operasi berbahaya.

Bagaimana NextPDF menanganinya

Ekosistem ini sengaja dibuat berlapis sehingga setiap paket memiliki satu tugas. Mesin inti merender PDF secara in-process. Jembatan framework menyesuaikan mesin tersebut dengan konvensi sebuah framework. Paket renderer mendelegasikan tata letak HTML atau Office ke mesin eksternal ketika mesin in-process bukan alat yang tepat. Connect mengubah mesin menjadi layanan jaringan. Tidak ada satu pun paket ini yang tumpang tindih dengan tanggung jawab paket lain, dan itulah yang membuat keputusan ini dapat ditangani. Anda tidak sedang memilih di antara alat yang saling bersaing. Anda sedang menyusun alat-alat yang saling melengkapi.

Buatlah keputusan berdasarkan kasus penggunaan. Tabel ini memetakan setiap skenario ke paket yang sesuai dan menyatakan kompromi yang perlu Anda terima.

Kasus penggunaan	Paket yang sesuai	Apa yang sebenarnya disediakan	Kompromi yang Anda terima
PDF di aplikasi Laravel	nextpdf/laravel	Service provider yang ditemukan otomatis, facade Pdf, PdfResponse (inline/unduh/streamed, header OWASP), GeneratePdfJob terantre dengan tries/timeout/backoff, registri terkunci yang aman untuk Octane	Satu dependensi Laravel 12; kapabilitas mesin tidak berubah
PDF di aplikasi Symfony	nextpdf/symfony	Bundle yang teregistrasi otomatis, PdfFactory yang dapat diinjeksi, PdfResponse, serta handler Messenger opsional untuk pembuatan asinkron	Satu dependensi bundle Symfony 7.2; kapabilitas tidak berubah
PDF di aplikasi CodeIgniter 4	nextpdf/codeigniter	Helper service('pdf') / pdf(), pustaka Pdf yang membungkus Document sekali pakai, PdfResponse, serta job terantre opsional	Satu dependensi CodeIgniter 4.6; kapabilitas tidak berubah
Dokumen membutuhkan CSS peramban penuh (flex/grid/font web) berdampingan dengan in-process	nextpdf/artisan	Chrome headless melalui CDP, dirender lalu diimpor kembali sebagai Form XObject sehingga teks tetap dapat dipilih; pool peramban	Runtime Chrome dan biaya memory/process-nya di host Anda
Dokumen Office (.docx, .xlsx) ke PDF	nextpdf/gotenberg	Jembatan PSR-18 ke microservice Gotenberg dengan transport yang diperkuat terhadap SSRF dan diikat ke IP	Satu layanan Gotenberg eksternal dan dependensi jaringan
HTML→PDF di edge / tanpa Chrome lokal	nextpdf/cloudflare	Cloudflare Browser Rendering melalui transport yang diikat, dengan fallback Chrome lokal opsional	Akun Cloudflare dan dependensi jaringan; fallback membutuhkan Artisan
Mesin dikonsumsi oleh layanan atau agen AI	nextpdf/server (Connect)	Satu mesin melalui MCP (stdio), REST (OpenAPI 3.1), dan gRPC; penemuan alat berbasis soft-dependency; gerbang konfirmasi manusia untuk alat berisiko tinggi	Mengoperasikan permukaan layanan; disiplin eksekusi deterministik

Human-factors note: Human-factors note

Ini dua keputusan yang independen, tetapi orang sering menggabungkannya. Pemilihan jembatan framework ditentukan oleh framework yang sudah Anda gunakan — pemilihan ini tidak memperluas atau membatasi apa yang dirender oleh mesin. Pemilihan renderer ditentukan oleh dokumen. Pertanyaan penentunya adalah apakah mesin CSS in-process sudah memadai, atau apakah dokumen benar-benar membutuhkan mesin tata letak peramban. Anda bisa saja membutuhkan jembatan framework tanpa renderer, renderer tanpa jembatan, keduanya, atau tidak satu pun. Memperlakukan keduanya sebagai satu pertanyaan adalah kesalahan integrasi yang paling umum terjadi, dan itulah sebabnya halaman ini memisahkan keduanya.

Apa yang dikatakan bukti

Halaman ini bersifat editorial — sebuah keputusan perutean — tetapi peruteannya berdasarkan isi manifes dan kelas utama setiap paket.

Evidence ¶ Editorial Evidence: Editorial

Jembatan framework ini nyata dan setara. Masing-masing mendeklarasikan dependensi framework dan registrasi otomatis di composer.json-nya (extra.laravel.providers, extra.symfony.bundles, Registrar CodeIgniter). Masing-masing juga menyertakan PdfResponse, pengikatan dokumen sekali pakai, dan job terantre opsional. Tidak ada satu pun dari paket-paket itu yang menambahkan kapabilitas rendering — semuanya menyesuaikan mesin yang sama. Para renderer itu nyata dan berbeda. Artisan bergantung pada chrome-php/chrome dan mengimpor kembali PDF Chrome sebagai Form XObject agar teks tetap dapat dipilih. Gotenberg dan Cloudflare adalah jembatan HTTP PSR-18 dengan transport yang secara eksplisit diperkuat terhadap SSRF dan diikat ke IP. Cloudflare dapat melakukan fallback ke Artisan ketika Worker tidak dapat dijangkau. composer.json milik Connect mendeklarasikan ketiga transport tersebut serta model soft-dependency yang membuat alat-alat muncul seiring paketnya dipasang, dan semuanya diatur oleh model risiko empat tingkat dengan gerbang konfirmasi manusia.

Cara halaman ini merutekan Anda didukung standar dari segi bentuknya: Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 menyatakan bahwa pembaca harus dapat dengan cepat menentukan apakah konten melayani tujuan mereka, dan Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x222 ISO/IEC/IEEE 26514:2022 §3.x222 mensyaratkan tautan dan referensi untuk menyatakan tujuannya — itulah sebabnya tabel ini menyebutkan paket konkret dan kompromi, alih-alih merujuk samar ke “sebuah integrasi”.

Contoh praktis

Keputusan ini berupa rangkaian pertanyaan jujur, bukan perbandingan fitur. Alur berikut menyelesaikan kasus-kasus umum.

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

Pelajarannya ada pada strukturnya: rendering dan pemanggilan adalah dua sumbu yang terpisah. Menjawab keduanya secara bersamaan adalah cara tim berakhir dengan renderer jarak jauh yang sebenarnya tidak mereka butuhkan, atau jembatan yang tidak menyelesaikan masalah fidelitas mereka.

Kesalahpahaman umum

Kesalahpahaman yang dominan adalah “Saya butuh paket renderer untuk membuat PDF.” Anda tidak membutuhkannya. Mesin inti membuat PDF secara in-process. Paket renderer hanya ada untuk kasus spesifik ketika mesin tata letak setara peramban diperlukan atau sumbernya berupa dokumen Office. Ketika mesin in-process sudah menghasilkan berkas yang benar, mengadopsi renderer secara refleks menambahkan dependensi runtime dan mode kegagalan tanpa manfaat apa pun.

Kesalahpahaman sebaliknya adalah “jembatan framework membuka kapabilitas.” Tidak demikian. Jembatan mengubah cara Anda memanggil mesin — facade, factory, respons, job terantre — bukan apa yang dapat dihasilkannya. Penandatanganan, PDF/A, dan faktur terstruktur adalah urusan tier dan mesin, tetap sama baik Anda memanggilnya melalui jembatan maupun secara langsung.

Batasan dan ruang lingkup

• Halaman ini merutekan; halaman ini tidak melakukan benchmark atau pemeringkatan. Halaman ini menyatakan apa yang disediakan setiap paket dan komprominya. Memilih di antaranya adalah keputusan Anda berdasarkan kendala Anda.
• Kapabilitas paket dibaca dari manifes dan kelas utamanya pada satu titik waktu. Perlakukan dokumentasi masing-masing paket sebagai sumber otoritatif untuk API-nya saat ini. Panduan ini adalah peta, bukan spesifikasi.
• Tidak ada perbandingan dengan kompetitor yang ditawarkan atau tersirat. Satu-satunya subjek adalah ekosistem NextPDF dan bagaimana bagian-bagiannya saling terhubung.
• Jembatan framework dan renderer adalah pilihan yang independen. Jembatan tidak memperluas kapabilitas mesin; renderer tidak bergantung pada framework.
• Renderer eksternal menambahkan dependensi ketersediaan. Gotenberg dan Cloudflare memperkenalkan panggilan jaringan dan layanan yang harus dioperasikan; itu adalah kompromi yang diterima, bukan biaya tersembunyi.
• Kapabilitas yang dibatasi tier bersifat ortogonal terhadap integrasi. Fitur komersial dibuka oleh tier, bukan oleh jembatan atau renderer mana pun; lihat ruang lingkup di bawah.

Ecosystem packages and tiering — edition availability

Edition	Availability
Core	○ Setiap paket integrasi (jembatan, Artisan, Gotenberg, Cloudflare, Connect) berfungsi dengan Core dan berlisensi Apache-2.0. Semuanya menyesuaikan atau mengekspos mesin; tidak ada yang membatasi fitur.
Pro	○ Kapabilitas komersial (penandatanganan baseline PAdES, PDF/A, barcode lanjutan ) dibuka oleh tier dan kemudian tersedia melalui integrasi mana pun, bukan dengan berpindah integrasi.
Enterprise	○ Faktur terstruktur, kebijakan validasi, dan gerbang konfirmasi manusia Connect untuk alat berisiko tinggi adalah kapabilitas tier, yang juga tidak bergantung pada integrasi.

Dokumen terkait

• Pipeline HTML — cakupan mesin CSS in-process, sehingga Anda tahu kapan renderer peramban benar-benar dibutuhkan.
• Kapan tidak menggunakan NextPDF — batas jujur untuk masalah dokumen yang tidak tepat ditangani mesin ini.
• Fondasi PHP 8.4 — batas minimum runtime yang dibagikan setiap paket dan apa yang dipertahankan jalur backport.

Glosarium

• Mesin inti — nextpdf/core, mesin PDF 2.0 in-process yang menjadi dasar semua paket lainnya.
• Jembatan framework — paket integrasi (Laravel/Symfony/CodeIgniter) yang menyesuaikan mesin dengan konvensi sebuah framework tanpa mengubah kapabilitasnya.
• Paket renderer — paket yang mendelegasikan tata letak HTML atau Office ke mesin eksternal (Artisan/Cloudflare/Gotenberg) ketika mesin in-process bukan alat yang tepat.
• Form XObject — fragmen konten PDF yang dapat dipakai ulang; Artisan mengimpor halaman yang dirender peramban sebagai salah satunya sehingga teksnya tetap dapat dipilih.
• NextPDF Connect — nextpdf/server, paket yang mengekspos mesin melalui MCP, REST, dan gRPC dengan permukaan eksekusi deterministik.
• Soft dependency — model Connect tempat alat muncul otomatis seiring paket NextPDF opsional dipasang, tanpa perubahan kode.