Mengonfigurasi paket Laravel NextPDF

Sekilas

config/nextpdf.php dipublikasikan oleh php artisan vendor:publish --tag=nextpdf-config. Setiap kunci memiliki fallback melalui variabel lingkungan dan nilai standar yang ditetapkan dalam kode. Halaman ini mencantumkan setiap kunci persis seperti yang muncul di config/nextpdf.php paket.

Pemasangan

php artisan vendor:publish --tag=nextpdf-config

Saat register() berjalan, provider juga menggabungkan nilai standar paket di bawah kunci config nextpdf. Kunci yang belum disetel kemudian kembali menggunakan nilai di bawah ini, bahkan sebelum Anda memublikasikan berkas config.

Gambaran konseptual

Sebagian besar variabel lingkungan menerima nama NEXTPDF_* maupun nama lawas TCPDF_*. Prefiks lawas tetap tersedia selama masa transisi yang didokumentasikan dalam UPGRADE.md. Gunakan NEXTPDF_* untuk deployment baru. Berkas config menentukan nilai dalam urutan ini: variabel lingkungan → nilai dari berkas yang dipublikasikan → nilai standar paket.

Permukaan API — kunci konfigurasi

Tata letak dokumen

Kunci	Env (utama)	Standar	Efek
page_format	NEXTPDF_PAGE_FORMAT	A4	Format halaman standar: A4, A3, A5, Letter, Legal, atau Tabloid
orientation	NEXTPDF_ORIENTATION	P	Tegak (P) atau lanskap (L)
unit	NEXTPDF_UNIT	mm	Satuan pengukuran: pt, mm, cm, atau in
defaults.creator	NEXTPDF_CREATOR	NextPDF	Metadata pembuat dokumen; diterapkan pada binding PdfDocumentInterface
defaults.author	NEXTPDF_AUTHOR	(kosong)	Metadata penulis; diterapkan hanya jika tidak kosong
defaults.language	NEXTPDF_LANG	en	Bahasa dokumen; diterapkan pada binding dokumen
defaults.margin_top / _right / _bottom / _left	—	10	Margin standar
defaults.font_family	—	dejavusans	Keluarga fon standar
defaults.font_size	—	12	Ukuran fon standar
defaults.trim_box	—	null	TrimBox [left, bottom, right, top] dalam poin, atau null
defaults.bleed_box	—	null	BleedBox [left, bottom, right, top] dalam poin, atau null

Provider menerapkan defaults.creator, defaults.language, dan (jika disetel) defaults.author ke setiap dokumen yang baru diselesaikan. Provider melewati defaults.author jika nilainya kosong.

Pengarsipan dan warna

Kunci	Env (utama)	Standar	Efek
pdfa	NEXTPDF_PDFA	null	Tingkat pengarsipan PDF/A: null, 4, 4e, atau 4f. Nilai non-null mengaktifkan PDF/A pada binding dokumen dan memerlukan nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	Direktori untuk fon TrueType tambahan; menetapkan jalur pencarian registri fon
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	Direktori cache fon yang telah diurai dan berkas sementara
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	Jalur profil ICC RGB; wajib untuk PDF/A
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	Profil ICC CMYK opsional untuk alur kerja cetak
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	Gunakan flock pada cache fon untuk mencegah kerusakan saat pekerja antrean konkuren menulis

Nilai pdfa non-null memerlukan tier Premium. Tanpa nextpdf/premium, menyelesaikan binding dokumen dengan pdfa yang disetel memunculkan kesalahan class-not-found untuk tipe versi PDF/A. Halaman ini tidak mendokumentasikan perilaku pengarsipan Premium. Lihat dokumentasi Premium.

Memori pekerja (runtime berumur panjang)

Kunci	Env (utama)	Standar	Efek
preload_fonts	—	[]	Jalur berkas fon absolut yang diurai saat boot pekerja. Registri fon dikunci setelah warmup
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	Anggaran cache gambar least recently used (LRU) dalam megabita (MB). 0 menonaktifkan caching. Tidak ada batas atas yang diberlakukan pada tingkat provider

Anggaran cache gambar tidak memiliki batas atas yang diberlakukan oleh provider. Gunakan batas memori kontainer atau php.inimemory_limit untuk membatasinya. Berkas config menyarankan maksimum praktis 256 MB.

Tanda tangan digital (Premium)

Kunci	Env (utama)	Standar	Efek
signature.enabled	NEXTPDF_SIGN_ENABLED	false	Jika false, atau jika sertifikat kosong, SignerInterface diselesaikan menjadi null
signature.certificate	NEXTPDF_SIGN_CERT	null	Jalur sertifikat penandatanganan
signature.private_key	NEXTPDF_SIGN_KEY	null	Jalur kunci privat
signature.password	NEXTPDF_SIGN_PASSWORD	(kosong)	Frasa sandi kunci
signature.extra_certs	—	[]	Jalur sertifikat CA perantara
signature.level	NEXTPDF_SIGN_LEVEL	B-B	Tingkat baseline PDF Advanced Electronic Signatures (PAdES) yang diteruskan ke penanda tangan

Paket Core yang didokumentasikan di sini tidak menyertakan implementasi penanda tangan; SignerInterface diselesaikan menjadi null hingga nextpdf/premium menyediakannya. Dengan Premium, level: B-B menghasilkan tanda tangan baseline PAdES B-B. Baseline PAdES yang lebih tinggi bergantung pada otoritas stempel waktu yang dikonfigurasi dan kapabilitas Premium; halaman ini tidak mendokumentasikan tingkat tersebut.

Otoritas stempel waktu

Kunci	Env (utama)	Standar	Efek
tsa.url	NEXTPDF_TSA_URL	null	Titik akhir otoritas stempel waktu (TSA). Jika kosong, TsaClient diselesaikan menjadi null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(kosong)	Kredensial HTTP TSA
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	Sertifikat / kunci klien untuk mutual Transport Layer Security (mTLS) ke TSA
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	Batas waktu HTTP dalam detik untuk klien PSR-18
tsa.pinned_public_keys	—	[]	Pin SubjectPublicKeyInfo (SPKI) SHA-256 Base64 (RFC 7469). Kosong menonaktifkan pinning
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	Memunculkan peringatan saat TSA menyajikan SPKI yang tidak di-pin
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	Mengizinkan HTTP teks polos ke TSA. Biarkan tetap false di produksi

Cache respons OCSP

Kunci	Env (utama)	Standar	Efek
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	Menyimpan respons Online Certificate Status Protocol (OCSP) dalam cache selama validasi
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	TTL cache dalam detik
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	Direktori cache; null membuat cache hanya berada di memori

Antrean

Kunci	Env (utama)	Standar	Efek
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	Koneksi antrean; null menggunakan koneksi standar
queue.queue	NEXTPDF_QUEUE_NAME	pdf	Antrean tempat GeneratePdfJob dikirim
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	Batas waktu per pekerjaan dalam detik

Perender Chrome CDP (ekstensi Artisan)

Kunci	Env (utama)	Standar	Efek
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	nilai env atau tidak disetel	Jalur ke biner Chrome/Chromium
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	Batas waktu rendering dalam detik
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(kosong)	CSS standar yang disuntikkan ke dalam HTML yang dirender
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	Menonaktifkan sandbox Chrome
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	Ukuran input HTML maksimum dalam bita

Bagian artisan hanya berlaku pada binding dokumen jika kelas browser-factory Chrome hadir (ekstensi nextpdf/artisan). Jika kelas tersebut tidak ada, bagian ini diabaikan.

Contoh kode — Produksi

resource: config/nextpdf.php (subset, verified against the published file)

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

Kasus tepi & jebakan

• Jika signature.enabled = true tetapi signature.certificate kosong, SignerInterface tetap diselesaikan menjadi null; kedua nilai harus disetel.
• tsa.url = null memaksa TsaClient menjadi null, bahkan jika kunci tsa.* lainnya terisi.
• signature.level = null kembali menggunakan PAdES B-B pada penanda tangan.
• image_cache_mb yang disetel ke null (bukan 0) kembali ke nilai standar 50 MB; 0 secara eksplisit menonaktifkan caching.
• Variabel lingkungan lawas TCPDF_* tetap dapat dibaca tetapi sudah usang. Bermigrasilah ke NEXTPDF_*.

Performa

Pembacaan config menggunakan akses array O(1). preload_fonts melakukan penguraian O(f) sekali saat boot pekerja untuk menurunkan latensi permintaan pertama. image_cache_mb yang lebih besar mengurangi pendekodean gambar berulang dengan biaya memori yang menetap di proses.

Catatan keamanan

tsa.allow_insecure_http melemahkan kepercayaan stempel waktu dan harus tetap false di produksi. URL TSA hanya boleh berasal dari konfigurasi tepercaya. Jika Anda mengeksposnya melalui antarmuka admin, gunakan firewall egress atau kebijakan DNS untuk memitigasi pemalsuan permintaan. Lihat /integrations/laravel/security-and-operations/.

Konformitas

Tidak ada standar normatif yang mengatur bentuk berkas konfigurasi. Semua kunci diverifikasi terhadap config/nextpdf.php paket pada revisi yang didokumentasikan. Premium menentukan semantik tingkat tanda tangan, yang berada di luar cakupan halaman Core ini.

Konteks komersial

Bagian signature dan tsa mengendalikan penandatanganan Premium saat nextpdf/premium terpasang. Kapabilitas Enterprise opsional ini tidak memerlukan perubahan kode paket Core. Lihat https://nextpdf.dev/get-license/?intent=laravel-signing.

Lihat juga

• /integrations/laravel/install/ — memublikasikan berkas config
• /integrations/laravel/production-usage/ — melihat konfigurasi yang diterapkan di controller nyata
• /integrations/laravel/security-and-operations/ — memperketat pengaturan TSA dan antrean
• /integrations/laravel/boot-and-discovery/ — melihat binding yang dikendalikan oleh setiap kunci