NextPDF Laravel paketinin yapılandırılması

Genel bakış

config/nextpdf.php dosyası php artisan vendor:publish --tag=nextpdf-config komutuyla yayımlanır. Her anahtar için bir ortam değişkeni yedeği ve sabit kodlanmış bir varsayılan değer bulunur. Bu sayfa, her anahtarı paketin config/nextpdf.php dosyasında göründüğü biçimde listeler.

Kurulum

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

Sağlayıcı, register() sırasında paket varsayılanlarını nextpdf yapılandırma anahtarının altında da birleştirir. Yapılandırma dosyası yayımlanmamış olsa bile tanımlanmamış anahtarlar aşağıdaki değerlere geri döner.

Kavramsal genel bakış

Çoğu ortam değişkeni, bir NEXTPDF_* adını ya da eski bir TCPDF_* adını kabul eder. Eski önek, UPGRADE.md dosyasında belgelenen geçiş döneminde kullanılabilir. Yeni dağıtımlar için NEXTPDF_* kullanın. Yapılandırma dosyası değerleri şu sırayla çözümlenir: ortam değişkeni → yayımlanmış dosya değeri → paket varsayılanı.

API yüzeyi — yapılandırma anahtarları

Belge yerleşimi

Anahtar	Ortam (birincil)	Varsayılan	Etki
page_format	NEXTPDF_PAGE_FORMAT	A4	Varsayılan sayfa biçimi: A4, A3, A5, Letter, Legal veya Tabloid
orientation	NEXTPDF_ORIENTATION	P	Dikey (P) veya yatay (L)
unit	NEXTPDF_UNIT	mm	Ölçü birimi: pt, mm, cm veya in
defaults.creator	NEXTPDF_CREATOR	NextPDF	Belge oluşturucu meta verisi; PdfDocumentInterface bağlamasına uygulanır
defaults.author	NEXTPDF_AUTHOR	(boş)	Yazar meta verisi; yalnızca boş olmadığında uygulanır
defaults.language	NEXTPDF_LANG	en	Belge dili; belge bağlamasına uygulanır
defaults.margin_top / _right / _bottom / _left	—	10	Varsayılan kenar boşlukları
defaults.font_family	—	dejavusans	Varsayılan yazı tipi ailesi
defaults.font_size	—	12	Varsayılan yazı tipi boyutu
defaults.trim_box	—	null	Punto cinsinden TrimBox [left, bottom, right, top] veya null
defaults.bleed_box	—	null	Punto cinsinden BleedBox [left, bottom, right, top] veya null

Sağlayıcı, defaults.creator, defaults.language ve (ayarlandığında) defaults.author değerlerini yeni çözümlenen her belgeye uygular. Değer boşsa sağlayıcı defaults.author değerini atlar.

Arşivleme ve renk

Anahtar	Ortam (birincil)	Varsayılan	Etki
pdfa	NEXTPDF_PDFA	null	PDF/A arşivleme düzeyi: null, 4, 4e veya 4f. Null olmayan bir değer, belge bağlamasında PDF/A’yı etkinleştirir ve şu paketi gerektirir: nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	Ek TrueType yazı tipleri için dizin; yazı tipi kaydının arama yolunu ayarlar
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	Çözümlenmiş yazı tipi ve geçici dosya önbellek dizini
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	RGB ICC profili yolu; PDF/A için gereklidir
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	Baskı iş akışları için isteğe bağlı CMYK ICC profili
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	Eşzamanlı kuyruk çalışanlarının yazması sırasında bozulmayı önlemek için yazı tipi önbelleğinde flock kullanır

pdfa için null olmayan bir değer Premium katmanını gerektirir. nextpdf/premium olmadan, pdfa ayarlanmış bir belge bağlamasını çözümlemek PDF/A sürüm türü için sınıf bulunamadı hatasına yol açar. Bu sayfa Premium arşivleme davranışını belgelemez. Premium belgelerine bakın.

Çalışan belleği (uzun ömürlü çalışma zamanları)

Anahtar	Ortam (birincil)	Varsayılan	Etki
preload_fonts	—	[]	Çalışan başlatılırken ayrıştırılan mutlak yazı tipi dosyası yolları. Yazı tipi kaydı, ısınma sonrasında kilitlenir
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	Megabayt (MB) cinsinden en uzun süredir kullanılmayan (LRU) görüntü önbelleği bütçesi. 0 önbelleğe almayı devre dışı bırakır. Sağlayıcı düzeyinde herhangi bir üst sınır uygulanmaz

Görüntü önbelleği bütçesi için sağlayıcı tarafından uygulanan bir üst sınır yoktur. Bunu sınırlamak için kapsayıcı düzeyinde bir bellek sınırı ya da php.inimemory_limit kullanın. Yapılandırma dosyası, pratikte 256 MB’lık bir üst sınır önerir.

Dijital imza (Premium)

Anahtar	Ortam (birincil)	Varsayılan	Etki
signature.enabled	NEXTPDF_SIGN_ENABLED	false	False olduğunda ya da sertifika boş olduğunda SignerInterface şu değere çözümlenir: null
signature.certificate	NEXTPDF_SIGN_CERT	null	İmzalama sertifikası yolu
signature.private_key	NEXTPDF_SIGN_KEY	null	Özel anahtar yolu
signature.password	NEXTPDF_SIGN_PASSWORD	(boş)	Anahtar parolası
signature.extra_certs	—	[]	Ara CA sertifikası yolları
signature.level	NEXTPDF_SIGN_LEVEL	B-B	İmzalayıcıya iletilen PDF Gelişmiş Elektronik İmzalar (PAdES) taban düzeyi

Burada belgelenen Core paketi bir imzalayıcı uygulaması içermez; SignerInterface, bir uygulama sağlanana kadar null olarak çözümlenir; bunu nextpdf/premium sağlar. Premium kullanıldığında level: B-B, bir PAdES B-B taban imzası üretir. Daha yüksek PAdES taban düzeyleri, yapılandırılmış bir zaman damgası otoritesine ve Premium yeteneğine bağlıdır; bu sayfa söz konusu düzeyleri belgelemez.

Zaman damgası otoritesi

Anahtar	Ortam (birincil)	Varsayılan	Etki
tsa.url	NEXTPDF_TSA_URL	null	Zaman damgası otoritesi (TSA) uç noktası. Boş olduğunda TsaClient şu değere çözümlenir: null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(boş)	TSA HTTP kimlik bilgileri
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	TSA ile karşılıklı aktarım katmanı güvenliği (mTLS) için istemci sertifikası / anahtarı
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	PSR-18 istemcisi için saniye cinsinden HTTP zaman aşımı
tsa.pinned_public_keys	—	[]	Base64 SHA-256 SubjectPublicKeyInfo (SPKI) sabitlemeleri (RFC 7469). Boş bırakıldığında sabitleme devre dışı kalır
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	TSA sabitlenmemiş bir SPKI sunduğunda uyarı yayımlar
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	TSA için düz metin HTTP’ye izin verir. Üretimde false bırakın

OCSP yanıt önbelleği

Anahtar	Ortam (birincil)	Varsayılan	Etki
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	Doğrulama sırasında çevrimiçi sertifika durumu protokolü (OCSP) yanıtlarını önbelleğe alır
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	Saniye cinsinden önbellek TTL’si
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	Önbellek dizini; null önbelleği yalnızca bellekte tutar

Kuyruk

Anahtar	Ortam (birincil)	Varsayılan	Etki
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	Kuyruk bağlantısı; null varsayılan bağlantıyı kullanır
queue.queue	NEXTPDF_QUEUE_NAME	pdf	İçine GeneratePdfJob işinin gönderildiği kuyruk
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	İş başına saniye cinsinden zaman aşımı

Chrome CDP işleyicisi (Artisan uzantısı)

Anahtar	Ortam (birincil)	Varsayılan	Etki
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	ortam değeri veya ayarlanmamış	Chrome/Chromium ikili dosyasının yolu
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	Saniye cinsinden işleme zaman aşımı
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(boş)	İşlenen HTML’ye enjekte edilen varsayılan CSS
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	Chrome korumalı alanını devre dışı bırakır
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	Bayt cinsinden en büyük HTML girişi boyutu

Yapılandırmadaki artisan bölümü, belge bağlamasına yalnızca bir Chrome tarayıcı fabrikası sınıfı mevcut olduğunda uygulanır (nextpdf/artisan uzantısı). Söz konusu sınıf bulunmadığında bölüm yok sayılır.

Kod örneği — üretim

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),
    ],
];

Uç durumlar ve püf noktaları

• signature.enabled = true olduğunda, signature.certificate boşsa SignerInterface yine null olarak çözümlenir; her iki değer de ayarlanmalıdır.
• tsa.url = null, TsaClient değerinin null olarak çözümlenmesini zorlar; diğer tsa.* anahtarları doldurulmuş olsa bile.
• signature.level = null, imzalayıcıda PAdES B-B düzeyine geri döner.
• image_cache_mb değerinin null olarak ayarlanması (0 değil) 50 MB’lık varsayılana geri döner; 0 önbelleğe almayı açıkça devre dışı bırakır.
• Eski TCPDF_* ortam değişkenleri okunabilir kalır ancak kullanımdan kaldırılmıştır. NEXTPDF_* değişkenlerine geçin.

Performans

Yapılandırma okuması O(1) dizi erişimi kullanır. preload_fonts, daha düşük ilk istek gecikmesi için çalışan başlatılırken tek seferlik bir O(f) ayrıştırma ödünleşimi getirir. Daha büyük bir image_cache_mb, işlemde yerleşik bellek pahasına tekrarlanan görüntü kod çözmeyi azaltır.

Güvenlik notları

tsa.allow_insecure_http zaman damgası güvenini zayıflatır ve üretimde false olarak kalmalıdır. TSA URL’leri yalnızca güvenilir yapılandırmadan gelmelidir. Bunları bir yönetim yüzeyi üzerinden açığa çıkarırsanız, istek sahteciliği riskini azaltmak için çıkış güvenlik duvarı ya da DNS ilkesi kullanın. Bkz. /integrations/laravel/security-and-operations/.

Uygunluk

Yapılandırma dosyasının biçimini düzenleyen normatif bir standart yoktur. Tüm anahtarlar, belgelenen revizyonda paketin config/nextpdf.php dosyasına göre doğrulanır. İmza düzeyi anlamları Premium tarafından yönetilir; bunlar bu Core sayfasının kapsamı dışındadır.

Ticari bağlam

İmza ve tsa bölümleri, nextpdf/premium kurulu olduğunda Premium imzalamayı yönlendirir. Bu isteğe bağlı Enterprise yeteneği, Core paketinde kod değişikliği gerektirmez. <https://nextpdf.dev/get-license/? adresine bakın.intent=laravel-signing>.

Ayrıca bkz.

• /integrations/laravel/install/ — yapılandırma dosyasını yayımlayın
• /integrations/laravel/production-usage/ — yapılandırmanın gerçek bir denetleyicide uygulanışını görün
• /integrations/laravel/security-and-operations/ — TSA ve kuyruk ayarlarını sıkılaştırın
• /integrations/laravel/boot-and-discovery/ — her anahtarın hangi bağlamayı yönlendirdiğini görün