Mengonfigurasi bundel Symfony NextPDF

Sekilas pandang

Atur seluruh perilaku bundel di bawah kunci root nextpdf dalam config/packages/nextpdf.yaml. Setiap kunci memiliki nilai standar, jadi Anda hanya perlu menetapkan nilai yang ingin diubah. Halaman ini mencerminkan Configuration.php secara persis.

Pohon konfigurasi

NextPDF\Symfony\DependencyInjection\Configuration mendefinisikan skemanya. Nilai yang tidak valid akan menggagalkan build container dengan Symfony InvalidConfigurationException.

Kunci tingkat atas

Kunci	Tipe	Standar	Validasi
page_format	enum	A4	salah satu dari A4, A3, A5, Letter, Legal, Tabloid
orientation	enum	P	salah satu dari P, L
unit	enum	mm	salah satu dari pt, mm, cm, in
pdfa	skalar	null	salah satu dari null, 4, 4e, 4f
fonts_path	skalar	%kernel.project_dir%/resources/fonts	—
cache_path	skalar	%kernel.cache_dir%/nextpdf	—
image_cache_mb	bilangan bulat	50	minimum 0
font_cache_locking	boolean	true	—
preload_fonts	daftar string	[]	—

icc_profile

Kunci	Tipe	Standar
icc_profile.rgb	skalar	null
icc_profile.cmyk	skalar	null

defaults

Berlaku untuk setiap dokumen yang dihasilkan oleh PdfFactory.

Kunci	Tipe	Standar
defaults.creator	skalar	NextPDF
defaults.author	skalar	(kosong)
defaults.language	skalar	en
defaults.margin_top	float	10.0
defaults.margin_right	float	10.0
defaults.margin_bottom	float	10.0
defaults.margin_left	float	10.0
defaults.font_family	skalar	dejavusans
defaults.font_size	float	12.0
defaults.trim_box	variabel	null
defaults.bleed_box	variabel	null

PdfFactory membaca creator, author, dan language dari bagian ini, lalu menerapkannya pada setiap dokumen baru. Bundel menyimpan kunci lainnya sebagai parameter container untuk digunakan oleh engine.

artisan

Hanya berlaku ketika nextpdf/artisan terpasang dan terdeteksi.

Kunci	Tipe	Standar
artisan.chrome_binary	skalar	null
artisan.render_timeout	bilangan bulat	30
artisan.default_css	skalar	(kosong)
artisan.no_sandbox	boolean	false
artisan.max_html_size	bilangan bulat	5000000

signature

Hanya berlaku ketika nextpdf/premium terpasang. Ketika bundel dan tingkat Pro tersedia, konfigurasi penandatanganan yang didukung adalah profil baseline B-B. Node level menerima nilai string di bawah ini untuk kompatibilitas skema dengan rangkaian konfigurasi NextPDF yang lebih luas. Bundel ini menyediakan kemampuan penandatanganan B-B. Profil di luar B-B didokumentasikan secara terpisah dalam dokumentasi NextPDF Premium dan tidak diklaim di sini.

Kunci	Tipe	Standar	Validasi
signature.enabled	boolean	false	—
signature.certificate	skalar	null	—
signature.private_key	skalar	null	—
signature.password	skalar	(kosong)	—
signature.extra_certs	daftar string	[]	—
signature.level	enum	B-B	himpunan yang diterima: B-B, B-T, B-LT, B-LTA (B-B disediakan; B-T/B-LT/B-LTA adalah nilai untuk kompatibilitas skema, bukan kemampuan Pro yang disediakan)

Compiler pass mendaftarkan layanan penandatangan hanya ketika signature.enabled bernilai true dan signature.certificate telah diatur; jika tidak, bagian ini menjadi tidak aktif.

tsa

Konfigurasi klien Time Stamp Authority (TSA), digunakan oleh penandatanganan Pro jika dikonfigurasi.

Kunci	Tipe	Standar
tsa.url	skalar	null
tsa.username	skalar	(kosong)
tsa.password	skalar	(kosong)
tsa.cert	skalar	null
tsa.key	skalar	null
tsa.timeout	bilangan bulat	30
tsa.allow_insecure_http	boolean	false
tsa.pinned_public_keys	daftar string	[]
tsa.warn_on_key_rotation	boolean	true

Bundel mendaftarkan layanan klien TSA hanya ketika tsa.url telah diatur.

ocsp_cache

Kunci	Tipe	Standar
ocsp_cache.enabled	boolean	true
ocsp_cache.ttl	bilangan bulat	86400
ocsp_cache.directory	skalar	null

messenger

Pengaturan untuk pembuatan secara asinkron, digunakan ketika symfony/messenger terpasang.

Kunci	Tipe	Standar
messenger.transport	skalar	async
messenger.timeout	bilangan bulat	120
messenger.retries	bilangan bulat	3

Konfigurasi acuan

Berkas konfigurasi yang menampilkan setiap bagian beserta nilai standarnya:

nextpdf:
    page_format: A4
    orientation: P
    unit: mm
    pdfa: ~
    fonts_path: '%kernel.project_dir%/resources/fonts'
    cache_path: '%kernel.cache_dir%/nextpdf'
    image_cache_mb: 50
    font_cache_locking: true
    preload_fonts: []
    icc_profile:
        rgb: ~
        cmyk: ~
    defaults:
        creator: NextPDF
        author: ''
        language: en
        margin_top: 10.0
        margin_right: 10.0
        margin_bottom: 10.0
        margin_left: 10.0
        font_family: dejavusans
        font_size: 12.0
        trim_box: ~
        bleed_box: ~
    artisan:
        chrome_binary: ~
        render_timeout: 30
        default_css: ''
        no_sandbox: false
        max_html_size: 5000000
    signature:
        enabled: false
        certificate: ~
        private_key: ~
        password: ''
        extra_certs: []
        level: B-B
    tsa:
        url: ~
        username: ''
        password: ''
        cert: ~
        key: ~
        timeout: 30
        allow_insecure_http: false
        pinned_public_keys: []
        warn_on_key_rotation: true
    ocsp_cache:
        enabled: true
        ttl: 86400
        directory: ~
    messenger:
        transport: async
        timeout: 120
        retries: 3

Layanan dan alias container

Bundel memuat definisi layanannya dari config/services.php. Tabel di bawah ini mencerminkan berkas tersebut secara persis.

ID layanan	Dibagikan	Publik	Catatan
NextPDF\Typography\FontRegistry	ya	—	dibangun dari nextpdf.fonts_path; logger PHP Standard Recommendation 3 (PSR-3) bersifat opsional
NextPDF\Contracts\FontRegistryInterface	(alias)	ya	alias dari FontRegistry
NextPDF\Graphics\ImageRegistry	ya	—	least-recently-used (LRU) dengan batas; diberi tag kernel.reset (reset)
NextPDF\Core\DocumentFactory	ya	—	menggunakan kedua registri bersama
NextPDF\Contracts\DocumentFactoryInterface	(alias)	ya	alias dari DocumentFactory
NextPDF\Symfony\Service\PdfFactory	ya	ya	membaca parameter defaults, pdfa, dan artisan
NextPDF\Contracts\PdfDocumentInterface	tidak	ya	factory [PdfFactory, create]
NextPDF\Core\Document	(alias)	—	alias dari PdfDocumentInterface
nextpdf.document	(alias)	ya	alias dari PdfDocumentInterface
NextPDF\Symfony\Http\PdfResponse	—	ya	helper stateless

Bundel juga mendaftarkan pengikatan kontrak EInvoice (EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface) hanya ketika kelas implementasi Premium yang sesuai tersedia. Setiap layanan tidak dibagikan, sehingga pemanggil menerima instans baru. Keadaan parser per panggilan tidak pernah bocor antarpermintaan.

Dibagikan versus tidak dibagikan

nextpdf.document (dan aliasnya) tidak dibagikan: setiap resolusi container mengembalikan dokumen yang berbeda. Berdasarkan PHP Standard Recommendation 11 (PSR-11), sebuah container dapat mengembalikan nilai yang berbeda pada pemanggilan get() berturut-turut dengan pengidentifikasi yang sama; lihat PSR-11 §1.1.2. Registri fon dibagikan dan dikunci setelah warmup. Data fon struktural diurai sekali per proses dan tidak dapat dimutasi selama permintaan berlangsung.

Layanan FontRegistry dan ImageRegistry menerima Psr\Log\LoggerInterface opsional; Symfony mengikatnya dengan nullOnInvalid(). Logger tetap menjadi kolaborator opsional yang dapat ditukar, sesuai dengan kontrak logger PSR-3.

Autowiring

PdfFactory, PdfResponse, antarmuka factory dokumen, dan antarmuka registri fon bersifat publik. Semuanya dapat diambil dari container atau diberi type hint pada controller dan layanan yang di-autowire. Constructor injection NextPDF\Symfony\Service\PdfFactory adalah titik masuk yang direkomendasikan.

Kasus batas dan jebakan

• pdfa diatur tanpa Pro — nilai disimpan tetapi diabaikan. PdfFactory menerapkan Portable Document Format/Archival (PDF/A) hanya ketika ekstensi Pro terdeteksi pada saat kompilasi.
• image_cache_mb: 0 — valid; menonaktifkan cache LRU gambar. Nilai negatif ditolak pada saat build.
• signature.enabled: true tanpa signature.certificate — layanan penandatangan tidak didaftarkan; konfigurasi menjadi tidak aktif secara diam-diam sesuai rancangan.
• %kernel.*% placeholder — fonts_path dan cache_path menggunakan parameter container Symfony; ganti dengan path absolut hanya ketika path literal diperlukan.

Kesesuaian

Setiap baris merupakan klaim normatif pada halaman ini, ditautkan ke reference_id 64-heks lengkap dari korpus standards development organization (SDO) yang berpagar. Provenans, termasuk manifes korpus dan transport pengambilan, berada di _sidecars/rag-citations.yaml.

Spesifikasi	Klausa	reference_id	Klaim
PSR-11	psr_11_container#1.1.2.p3.b		get() dapat mengembalikan nilai yang berbeda per resolusi
PSR-3	psr_3_logger#x3.p17		Kolaborator LoggerInterface bersifat opsional

Konteks komersial

Bagian signature dan tsa hanya berlaku ketika nextpdf/premium (Pro) terpasang. 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/ — instal dan daftarkan bundel.
• /integrations/symfony/overview/ — tinjau ringkasan kemampuan.
• /integrations/symfony/production-usage/ — keamanan worker dan pola asinkron.
• /integrations/symfony/boot-and-discovery/ — lihat bagaimana konfigurasi diselesaikan selama boot.