NextPDF Laravel paketiyle ilgili sorun giderme

Bir bakışta

Bu sayfayı, gözlemlenebilir her paket hatasını kaynak düzeyinde doğrulanmış kök nedeniyle eşleştirmek için kullanın. Her girişte belirti, neden ve çözüm yer alır.

Kurulum

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Kavramsal genel bakış

Bildirilen sorunların çoğu beş gruba ayrılır: keşif, kapsayıcı çözümleme, imzalama, kuyruk işleri ve HTTP dosya adları. Paket, tasarımı gereği hatayı açıkça bildirerek başarısız olur. Yapılandırılmamış isteğe bağlı özellikler null döndürür; güvenli olmayan girdiler ise türlenmiş istisnalar oluşturur. Belirti genellikle nedeni doğrudan gösterir.

API yüzeyi — belirtiden nedene

Keşif ve önyükleme

Belirti	Doğrulanmış neden	Çözüm
Sağlayıcı kurulumdan sonra kaydedilmedi	Uygulama keşfi şu anahtarla devre dışı bırakıyor: extra.laravel.dont-discover	Paketi dont-discover listesinden kaldırın veya NextPdfServiceProvider sağlayıcısını elle şuraya kaydedin: bootstrap/providers.php
config('nextpdf') boş	Bildirilen bağlamalardan hiçbiri çözümlenmediği için yapılandırma birleştirilmedi (ertelenmiş sağlayıcı)	Herhangi bir provides() girişini çözümleyin veya keşfi şu komutla doğrulayın: php artisan package:discover --ansi
config/nextpdf.php publish tarafından oluşturulmadı	Publish etiketi eşleşmiyor	Tam olarak şu etiketi kullanın: php artisan vendor:publish --tag=nextpdf-config
RuntimeException: “NextPDF requires the ext-mbstring/ext-zlib PHP extension”	Gerekli bir PHP uzantısı çalışma zamanında eksik	Şu uzantıları kurun veya etkinleştirin: mbstring, zlib; ilgili dosya: php.ini

Kapsayıcı çözümleme

Belirti	Doğrulanmış neden	Çözüm
app(SignerInterface::class) şunu döndürüyor: null	İmzalama devre dışı veya sertifika şurada boş: nextpdf.signature	Şunu ayarlayın: signature.enabled = true ve geçerli bir signature.certificate; imzalayıcı somut sınıfını sağlamak için nextpdf/premium paketini kurun
app(TsaClient::class) şunu döndürüyor: null	nextpdf.tsa.url boş	Şunu yapılandırın: tsa.url (ve gerektiğinde credentials/pins)
Bir PDF/A sürüm türü için sınıf bulunamadı	nextpdf.pdfa null değil, ancak nextpdf/premium kurulu değil	Şunu kurun: nextpdf/premium; veya pdfa değerini yeniden şuna ayarlayın: null
Bir e-fatura sözleşmesi çözümlenirken sınıf bulunamadı	Bağlamalar kayıtlı, ancak Premium somut sınıfları mevcut değil	Şunu kurun: nextpdf/premium; e-fatura sözleşmeleri tembel olarak çözümlenir ve Premium olmadan yalnızca ilk çözümlemede başarısız olur
Aynı belge iki mantıksal işlem arasında değişti	Belge bağlaması bir fabrikadır; çözümlenmiş tek bir örneği yeniden kullandınız	Her belge için yeni bir PdfDocumentInterface çözümleyin

Bir kapsayıcıda giriş yoksa get() çağrısı, bulunamadı istisnası oluşturur (PHP Standart Önerisi 11 (PSR-11) §1.1.2). E-fatura sözleşmeleri bağlanmıştır; bu nedenle kapsayıcının has() çağrısı true döndürür. Hatayı kapsayıcının kendisi değil, eksik Premium somut sınıfı oluşturulurken üretir.

Kuyruk işleri

Belirti	Doğrulanmış neden	Çözüm
InvalidArgumentException: Path traversal sequences are not allowed	Çıktı yolu bir .. bölümü içeriyor	Depolama dizininizin altında, üst dizine çıkış içermeyen mutlak bir yol kullanın
InvalidArgumentException: Stream wrappers are not allowed	Yol, şuna benzer bir şema kullanıyor: php://	Düz bir dosya sistemi yolu kullanın
InvalidArgumentException: Output path contains null bytes	Yol bir \0 baytı içeriyor	Yolu göndermeden önce temizleyin
InvalidArgumentException: Output path must end with .pdf extension	Yol .pdf ile bitmiyor (büyük/küçük harfe duyarsız)	Bir .pdf (veya .PDF) son eki kullanın
İş çalışıyor, ancak dosya boş veya hatalı	Oluşturucu kapanışı (closure), yapılandırılmış belgeyi döndürmedi	Belgeyi oluşturucudan döndürün; iş döndürülen değeri kaydeder
İş, yanlış kuyruğu veya zaman aşımını kullanıyor	nextpdf.queue.* beklendiği gibi ayarlı değil	Şunları ayarlayın: queue.queue, queue.connection ve queue.timeout; tries ve backoff alt sınıf oluşturmayı gerektirir

Yol denetimleri çalışan (worker) tarafında handle() içinde çalışır; bu nedenle hatalı bir yol gönderim sırasında değil, yürütme sırasında başarısız olur. Bu kasıtlıdır: çalışan, serileştirilmiş kuyruk yükünü tükettiği yerde doğrular.

HTTP yanıtları ve dosya adları

Belirti	Doğrulanmış neden	Çözüm
İndirme dosya adı beklenmedik şekilde document.pdf oluyor	Boş bir dosya adı geçirdiniz; fabrika varsayılan adı kullanır	Boş olmayan bir dosya adı geçirin
Dosya adı yolunu veya özel karakterlerini kaybetti	Dosya adı temizleyicisi yol ayırıcılarını, denetim karakterlerini ve null baytları kaldırır	Yalnızca temel dosya adını geçirin; bu sıkılaştırma beklenen davranıştır
ASCII olmayan dosya adı, bazı istemcilerde bozuk karakterler (mojibake) gösteriyor	Yanıt, ASCII olmayan adlar için Request for Comments 5987 (RFC 5987) filename*= değerini yayar; eski istemciler ASCII yedeğini okur	Bu beklenen davranıştır; eski bir istemcinin tam eşleşmesi gerekiyorsa ASCII açısından güvenli bir ad sağlayın
Akışlı yanıtta şu başlık yok: Content-Length	Akışlı yanıtlar, tasarımı gereği Content-Length başlığını atlar (parçalı çıktı)	Bu beklenen davranıştır; uzunluk başlığı gerekiyorsa akışsız inline()/download() kullanın

Kod örneği — tanılama

# Confirm the provider is discovered
php artisan package:discover --ansi

# Inspect merged configuration
php artisan tinker --execute="dump(config('nextpdf.queue'));"

resource: src/Laravel/NextPdfServiceProvider.php (null-check pattern)

<?php

declare(strict_types=1);

use NextPDF\Contracts\SignerInterface;

$signer = app(SignerInterface::class);

if ($signer === null) {
    // Signing not configured, or nextpdf/premium not installed.
    // Continue without a signature, or fail with a clear message.
}

Uç durumlar ve dikkat edilmesi gerekenler

• Ertelenmiş sağlayıcı kullanıldığında, yeni bir kurulum ilgili ilk çözümlemeye kadar “bozuk” görünebilir. package:discover çıktısında paketin listelenmesini başarı sinyali olarak değerlendirin.
• Değer image_cache_mb = null olduğunda, paket 50 MB değerine geri döner; önbelleği yalnızca 0 devre dışı bırakır. “Önbellek devre dışı kalmıyor” şeklindeki bildirimlerde genellikle null kullanılmıştır.
• Değer signature.level = null olduğunda, paket sessizce PDF Gelişmiş Elektronik İmzaları (PAdES) B-B düzeyine geri döner. “Beklenmeyen B-B” şeklindeki bildirimlerde genellikle düzey ayarlanmadan bırakılmıştır.

Performans

Uzun ömürlü bir çalışanda ilk istekler yavaşsa, yazı tipi kaydı talep üzerine ayrıştırılıyordur. Isınma işleminin çalışan önyüklemesinde bir kez çalışması için nextpdf.preload_fonts değerini doldurun. Ayrıntılar için /integrations/laravel/configuration/ ve /integrations/laravel/boot-and-discovery/ adreslerine bakın.

Güvenlik notları

Yol ve dosya adı reddedilmeleri hata değil, güvenlik denetimleridir. Bunları önceden kod çözerek veya denetimleri gevşeterek aşmaya çalışmayın. Bunun yerine, dosya çıktısını denetimli bir depolama yolu üzerinden yönlendirin. Bkz. /integrations/laravel/security-and-operations/.

Uygunluk

İddia	Kaynak	Madde	reference_id
Eksik kapsayıcı girişi, get() çağrısında bulunamadı hatasına yol açar	PSR-11 Container	§1.1.2

Ayrıca bkz.

• /integrations/laravel/install/ — keşif ve publish adımları
• /integrations/laravel/configuration/ — her anahtar ve varsayılan değeri
• /integrations/laravel/production-usage/ — bağımlılık enjeksiyonu (DI) ve kuyruk desenleri
• /integrations/laravel/security-and-operations/ — yol denetimlerinin neden var olduğu