Ikhtisar integrasi NextPDF Symfony

Sekilas pandang

nextpdf/symfony adalah bundel resmi Symfony 7 untuk mesin NextPDF. Bundel ini menghubungkan mesin ke kontainer Symfony dan menyediakan document factory yang dapat diinjeksikan ke layanan Anda sendiri. Bundel ini juga menyertakan helper respons Hypertext Transfer Protocol (HTTP) dan jalur untuk menghasilkan berkas Portable Document Format (PDF) secara asinkron, sehingga pekerjaan dapat berjalan di latar belakang.

Apa yang disediakan bundel

NextPDF Symfony mengikat mesin nextpdf/core ke aplikasi Symfony sebagai bundel standar. Bundel ini menambahkan komponen penyusun berikut; masing-masing telah diverifikasi terhadap sumber bundel di src/Symfony/:

• Titik masuk bundel — NextPDF\Symfony\NextPdfBundle memperluas kelas dasar Bundle Symfony dan mendaftarkan satu compiler pass.
• Ekstensi dependency-injection — NextPDF\Symfony\DependencyInjection\NextPdfExtension memuat definisi layanan, mengubah pohon konfigurasi menjadi parameter kontainer, dan mengekspos alias konfigurasi nextpdf.
• Pohon konfigurasi bertipe — NextPDF\Symfony\DependencyInjection\Configuration mendefinisikan skema konfigurasi nextpdf. Kelas ini memvalidasi nilai enum, menetapkan nilai standar, dan menggunakan placeholder parameter %kernel.*%.
• Document factory yang dapat diinjeksikan — NextPDF\Symfony\Service\PdfFactory menghasilkan instance NextPDF\Core\Document baru yang sudah terkonfigurasi. Layanan ini merupakan padanan Symfony untuk facade statis.
• Helper respons HTTP — NextPDF\Symfony\Http\PdfResponse membangun respons inline, unduhan, dan streamed dengan sekumpulan header keamanan tetap yang selaras dengan Open Worldwide Application Security Project (OWASP).
• Jalur pembuatan asinkron — NextPDF\Symfony\Message\GeneratePdfMessage, NextPDF\Symfony\Message\GeneratePdfHandler, dan NextPDF\Symfony\Message\PdfBuilderInterface terintegrasi dengan Symfony Messenger sehingga rendering PDF dapat berjalan pada sebuah worker.
• Pendeteksi ekstensi pada waktu kompilasi — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass mendeteksi ekstensi NextPDF opsional dan mendaftarkan layanannya hanya ketika ekstensi tersebut tersedia.

Kontrak kontainer

Bundel mendaftarkan sejumlah kecil layanan kontainer publik yang stabil. Layanan dokumen nextpdf.document (diberi alias NextPDF\Contracts\PdfDocumentInterface dan NextPDF\Core\Document) tidak dibagikan: setiap resolusi layanan mengembalikan dokumen sekali pakai yang berbeda. Hal ini sesuai dengan kontrak kontainer PHP Standard Recommendation 11 (PSR-11): dua panggilan get() berturut-turut dengan pengidentifikasi yang sama dapat mengembalikan nilai yang berbeda bergantung pada konfigurasi kontainer — lihat PSR-11 §1.1.2. Pengikatan yang tidak dibagikan ini disengaja. Dokumen mengakumulasi state pada setiap rendering, sehingga instance baru per permintaan mencegah state bocor antarpermintaan pada worker yang berjalan lama.

Registri fon (NextPDF\Contracts\FontRegistryInterface) bekerja sebaliknya: ia merupakan singleton yang dibagikan. Registri gambar memiliki tag kernel.reset, sehingga cache terbatasnya dibersihkan di antara permintaan pada worker FrankenPHP dan Messenger. Halaman konfigurasi mendokumentasikan tabel layanan dan alias selengkapnya.

Pencatatan log opsional

Registri fon dan gambar menerima logger PHP Standard Recommendation 3 (PSR-3) opsional. Bundel mengikat Psr\Log\LoggerInterface hanya ketika aplikasi menyediakannya (nullOnInvalid()). Karena itu, pencatatan log merupakan kolaborator opsional, bukan dependensi wajib. Hal ini konsisten dengan kontrak logger PSR-3, yang memosisikan logger sebagai kolaborator yang diinjeksikan dan dapat ditukar (PSR-3).

Kemampuan inti versus opsional

Bundel ini sendiri merupakan perangkat lunak inti Apache-2.0. Beberapa kemampuan hanya tersedia ketika Anda memasang paket opsional bersama bundel:

Kemampuan	Membutuhkan	Deteksi
Pembuatan PDF, PdfFactory, PdfResponse	hanya inti	selalu tersedia
Pembuatan asinkron	symfony/messenger	handler aktif ketika Messenger terpasang
Perenderan HTML Chrome DevTools Protocol (CDP)	nextpdf/artisan	pemeriksaan class_exists pada waktu kompilasi
Pengarsipan PDF/A, tanda tangan digital	nextpdf/premium (memasang Pro)	pemeriksaan class_exists pada waktu kompilasi

Ketika nextpdf/premium terpasang, bundel dapat menerapkan konfigurasi tanda tangan baseline PDF Advanced Electronic Signatures (PAdES) B-B. Profil tanda tangan yang lebih tinggi berada di luar cakupan dokumentasi bundel ini. Untuk matriks edisi, lihat dokumentasi NextPDF Premium.

Kapan menggunakan bundel ini

Gunakan nextpdf/symfony ketika Anda membuat PDF di dalam aplikasi Symfony 7 atau worker HTTP. Bundel ini memberi Anda layanan yang dikelola kontainer, registri yang aman digunakan di worker, dan respons unduhan yang aman, sehingga Anda tidak perlu menyambungkan mesin secara manual. Jika Anda hanya memerlukan pembuatan sekali pakai dalam sebuah skrip, paket inti nextpdf/core saja sudah cukup.

Kesesuaian

Setiap baris adalah klaim normatif yang dibuat pada halaman ini dan dipetakan ke reference_id heksadesimal 64 digit penuh dari korpus standards development organization (SDO) yang aksesnya dibatasi. Provenansnya (manifes korpus, transport pengambilan) tersedia di _sidecars/rag-citations.yaml.

Spesifikasi	Klausa	reference_id	Klaim
PSR-11	psr_11_container#1.1.2.p3.b		Kontrak nilai kembalian get() kontainer
PSR-3	psr_3_logger#x3.p17		Dependensi opsional LoggerInterface

Konteks komersial

Tanda tangan digital dan pengarsipan PDF/A tersedia ketika nextpdf/premium (Pro) dipasang bersama bundel. Kemampuan Pro opsional ini tidak memerlukan perubahan kode pada bundel Core yang didokumentasikan di sini. Lihat </get-license/?intent=symfony-pro>.

Lihat juga

• /integrations/symfony/install/ — cara memasang dan mendaftarkan bundel.
• /integrations/symfony/configuration/ — pohon konfigurasi nextpdf selengkapnya dan tabel layanan.
• /integrations/symfony/quickstart/ — controller yang dapat dijalankan dan contoh asinkron.
• /integrations/symfony/boot-and-discovery/ — bagaimana Symfony menemukan dan melakukan boot pada bundel.
• /integrations/symfony/production-usage/ — keamanan worker, streaming, dan pola asinkron.