NextPDF Symfony paketinde sorun giderme

Genel bakış

Sorunların çoğu dört alandan birinden kaynaklanır: keşif, yapılandırma doğrulaması, container bağlama veya Messenger yönlendirmesi. Her bölüm bir belirtiyi arkasındaki paket davranışıyla eşleştirir, ardından düzeltmeyi doğrulamanız için bir konsol komutu verir.

Paket kayıtlı değil

Belirti: PdfFactory bağımlılığını otomatik olarak bağlayamıyorsunuz veya debug:container nextpdf hiçbir şey döndürmüyor.

Neden: paket config/bundles.php dosyasına eklenmemiştir. Flex çalışmamış olabilir veya uygulama Flex kullanmıyor olabilir.

Çözüm:

php bin/console debug:container nextpdf

Komut hiçbir hizmet döndürmüyorsa paketi elle ekleyin:

return [
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

Paketin composer.json dosyası, otomatik kayıt ipucunu extra.symfony.bundles altında içerir. Bu yalnızca Flex etkin olan uygulamalar için geçerlidir.

Açılış, eksik bir PHP uzantısı nedeniyle başarısız oluyor

Belirti: çekirdek, açılış sırasında bir RuntimeException fırlatıyor; istisna ext-mbstring veya ext-zlib uzantısından söz eder.

Neden: bu, paketin bilinçli hızlı başarısızlık koruması olan NextPdfExtension::guardRequiredExtensions() mekanizmasından kaynaklanır. Bir kusur değildir.

Çözüm: adı geçen uzantıyı php.ini içinde etkinleştirin, ardından çalışma zamanını yeniden başlatın. Aşağıdaki komutla doğrulayın:

php -m | grep -E 'mbstring|zlib'

Yapılandırma derleme zamanında reddediliyor

Belirti: Symfony, bir Symfony\Component\Config\Definition\Exception\InvalidConfigurationException istisnasını cache:clear veya cache:warmup sırasında fırlatıyor.

Neden: bir değer şemaya uymuyor. Configuration.php şu kısıtlamaları tanımlar:

• page_format şunlardan biri olmalıdır: A4, A3, A5, Letter, Legal, Tabloid.
• orientation değeri P veya L olmalıdır.
• unit şunlardan biri olmalıdır: pt, mm, cm, in.
• pdfa değeri null, 4, 4e veya 4f olmalıdır.
• image_cache_mb değeri >= 0 olmalıdır.

Çözüm: birleştirilmiş yapılandırmayı görüntüleyin, ardından başarısız olan anahtarı düzeltin:

php bin/console debug:config nextpdf

PDF/A veya imzalama etki etmiyor

Belirti: pdfa veya signature bölümü ayarlanmış, ancak çıktı sıradan bir Portable Document Format (PDF) dosyası olarak kalıyor.

Neden: bu yetenekler nextpdf/premium gerektirir. Derleme zamanında PdfFactory yalnızca Pro uzantısını algıladığında PDF/A’yı uygular. Derleyici geçişi bir imzalayıcıyı yalnızca signature.enabled değeri true ve signature.certificate ayarlandığında kaydeder.

Çözüm: Premium’un kurulu olduğunu ve imzalayıcı hizmetinin var olduğunu doğrulayın:

composer show nextpdf/premium
php bin/console debug:container --show-private | grep -i signer

Premium yoksa paket yapılandırmayı saklar, ancak bilinçli olarak etkisiz bırakır. Paketin Pro’yla belgelenmiş imzalama yeteneği temel B-B profilidir. NextPDF Premium belgeleri B-B dışındaki profilleri de kapsar.

Chrome işleme hiçbir sonuç üretmiyor

Belirti: artisan yapılandırması göz ardı ediliyor.

Neden: Chrome DevTools Protocol (CDP) işleme nextpdf/artisan gerektirir. Derleyici geçişi, derleme zamanında bunu class_exists ile denetler. Uzantı yoksa işleyici bağlanmaz.

Çözüm:

composer show nextpdf/artisan
php bin/console cache:clear   # re-run the compile-time probe

Denetim, container derlemesi sırasında çalışır. Uzantıyı kurduktan sonra yeni bir cache:clear çalıştırın.

Messenger işleyicisi hiç çağrılmıyor

Belirti: GeneratePdfMessage gönderiyorsunuz, ancak hiçbir PDF yazılmıyor.

Nedenler ve çözümler:

• İleti yönlendirilmemiş — NextPDF\Symfony\Message\GeneratePdfMessage iletisini config/packages/messenger.yaml içinde bir taşımaya eşleyen bir yönlendirme girdisi ekleyin, ardından bir işçi çalıştırın (php bin/console messenger:consume <transport>).
• Oluşturucu konumlandırıcıda değil — işleyici, oluşturucuyu sınıf dizesi kimliğine göre bir PHP Standards Recommendation 11 (PSR-11) konumlandırıcısından alır. Container tanımlayıcısı, bir girdiyi benzersiz biçimde tanımlayan bir dizedir (PSR-11 §1.1.2). Konumlandırıcıda oluşturucu sınıfı kayıtlı değilse işleyici bir RuntimeException fırlatır; bu istisna, yapılandırılan oluşturucunun PdfBuilderInterface arayüzünü uygulaması gerektiğini belirtir. Oluşturucuyu kaydedin, ardından konumlandırıcıdan ona referans verin.

Yönlendirmeyi ve konumlandırıcıyı inceleyin:

php bin/console debug:messenger
php bin/console debug:container --tag=container.service_locator

İleti, gönderim sırasında InvalidArgumentException ile reddediliyor

Belirti: GeneratePdfMessage oluşturulması bir InvalidArgumentException fırlatıyor.

Neden: ileti veri aktarım nesnesi (DTO), girdilerini doğrular. Doğrulama sırasında reddetme kuralları şunlardır:

• boş çıktı yolu veya boş bayt içeren bir yol;
• bir akış sarmalayıcı şeması (örneğin php://...);
• bir .. yol geçişi segmenti (POSIX veya Windows ayırıcıları);
• sonu .pdf ile bitmeyen bir çıktı yolu (büyük/küçük harfe duyarsız);
• sözdizimsel olarak geçerli bir sınıf adı olmayan bir builderClass.

Çözüm: .pdf ile biten mutlak bir dosya sistemi yolu ve gerçek, tam nitelikli bir oluşturucu sınıf adı iletin.

Bir belge güncel olmayan veri taşıyor

Belirti: oluşturulan bir PDF, önceki bir isteğin içeriğini taşıyor.

Neden: uzun süre çalışan bir işçi, istekler arasında bir Document örneğini tuttu. Belge hizmeti, tam da bunu önlemek için paylaşımsız olarak tanımlanmıştır.

Çözüm: PdfFactory::create() yöntemini istek kapsamındaki yöntemin içinde çağırın. Döndürülen belgeyi asla paylaşılan bir hizmette saklamayın.

Tanılama komutları başvurusu

php bin/console debug:container nextpdf          # bundle services
php bin/console debug:config nextpdf             # merged configuration
php bin/console debug:container --show-private   # internal definitions
php bin/console debug:messenger                  # message routing
php bin/console messenger:consume <t> -vv        # verbose consume

Uygunluk

Her satır, bu sayfada yer alan normatif bir iddiayı temsil eder ve geçitli standartlar geliştirme kuruluşu (SDO) corpus’undaki 64 karakterlik onaltılık bir reference_id değerine sabitlenmiştir. Corpus manifestosu ve geri alma taşıması dahil olmak üzere kaynak bilgisi _sidecars/rag-citations.yaml içinde yer alır.

Spesifikasyon	Madde	reference_id	İddia
PSR-11	psr_11_container#1.1.2.p4		Container has()/get() tanımlayıcı sözleşmesi

Ayrıca bakınız

• /integrations/symfony/install/ — kurulum ve kayıt.
• /integrations/symfony/configuration/ — tam şema ve kısıtlamalar.
• /integrations/symfony/boot-and-discovery/ — keşif ve açılış dizisi.
• /integrations/symfony/security-and-operations/ — güvenlik başlıkları ve yol doğrulaması.