Pemecahan masalah bundle NextPDF Symfony

Sekilas

Sebagian besar masalah berasal dari salah satu dari empat area: penemuan, validasi konfigurasi, perkabelan container, atau perutean Messenger. Setiap bagian mengaitkan gejala dengan perilaku bundle di baliknya, lalu memberi Anda perintah konsol untuk memverifikasi perbaikannya.

Bundle tidak terdaftar

Gejala: Anda tidak dapat meng-autowire PdfFactory, atau debug:container nextpdf tidak mengembalikan apa pun.

Penyebab: Bundle tidak ditambahkan ke config/bundles.php. Flex mungkin belum dijalankan, atau aplikasi mungkin tidak menggunakan Flex.

Solusi:

php bin/console debug:container nextpdf

Jika perintah tersebut tidak mengembalikan layanan apa pun, tambahkan bundle secara manual:

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

Berkas composer.json milik bundle berisi petunjuk pendaftaran otomatis di bawah extra.symfony.bundles. Petunjuk ini hanya berlaku untuk aplikasi yang mengaktifkan Flex.

Boot gagal karena ekstensi PHP tidak ada

Gejala: kernel melemparkan RuntimeException yang menyebut ext-mbstring atau ext-zlib saat boot.

Penyebab: Ini berasal dari NextPdfExtension::guardRequiredExtensions(), guard fail-fast yang memang sengaja disediakan oleh bundle. Ini bukan bug.

Solusi: aktifkan ekstensi yang disebutkan di php.ini, lalu mulai ulang runtime. Konfirmasikan dengan:

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

Konfigurasi ditolak pada waktu build

Gejala: Symfony melemparkan Symfony\Component\Config\Definition\Exception\InvalidConfigurationException selama cache:clear atau cache:warmup.

Penyebab: ada nilai yang berada di luar skema. Configuration.php mendefinisikan batasan berikut:

• page_format harus salah satu dari A4, A3, A5, Letter, Legal, Tabloid.
• orientation harus P atau L.
• unit harus salah satu dari pt, mm, cm, in.
• pdfa harus null, 4, 4e, atau 4f.
• image_cache_mb harus >= 0.

Solusi: tampilkan konfigurasi hasil penggabungan, lalu perbaiki kunci yang gagal:

php bin/console debug:config nextpdf

PDF/A atau penandatanganan tidak berpengaruh

Gejala: pdfa atau bagian signature telah disetel, tetapi keluarannya berupa berkas Portable Document Format (PDF) biasa.

Penyebab: kemampuan ini memerlukan nextpdf/premium. Saat kompilasi, PdfFactory menerapkan PDF/A hanya saat mendeteksi ekstensi Pro. Compiler pass mendaftarkan penanda tangan hanya saat signature.enabled bernilai true dan signature.certificate telah disetel.

Solusi: pastikan Premium telah terpasang dan layanan penanda tangan tersedia:

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

Jika Premium tidak ada, bundle menyimpan konfigurasi tetapi sengaja membiarkannya tidak aktif. Kemampuan penandatanganan bundle yang didokumentasikan untuk Pro adalah profil baseline B-B. Dokumentasi NextPDF Premium mencakup profil di luar B-B.

Perenderan Chrome tidak melakukan apa pun

Gejala: konfigurasi artisan diabaikan.

Penyebab: Renderer Chrome DevTools Protocol (CDP) memerlukan nextpdf/artisan. Compiler pass memeriksa keberadaannya dengan class_exists saat kompilasi. Jika ekstensi tidak ada, renderer tidak ikut dikabelkan.

Solusi:

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

Pemeriksaan ini berjalan selama kompilasi container. Setelah Anda memasang ekstensi, jalankan kembali cache:clear.

Handler Messenger tidak pernah dipanggil

Gejala: Anda mengirimkan GeneratePdfMessage, tetapi tidak ada PDF yang ditulis.

Penyebab dan solusi:

• Pesan tidak dirutekan — tambahkan entri perutean yang memetakan NextPDF\Symfony\Message\GeneratePdfMessage ke transport dalam config/packages/messenger.yaml, lalu jalankan worker (php bin/console messenger:consume <transport>).
• Builder tidak ada di locator — handler mengambil builder dari locator PHP Standards Recommendation 11 (PSR-11) berdasarkan id class-string-nya. Pengidentifikasi container adalah string yang mengidentifikasi sebuah entri secara unik (PSR-11 §1.1.2). Jika locator tidak memiliki kelas builder yang terdaftar, handler melemparkan RuntimeException yang menyatakan bahwa builder yang dikonfigurasi harus mengimplementasikan PdfBuilderInterface. Daftarkan builder, lalu rujuk builder tersebut dari locator.

Periksa perutean dan locator:

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

Pesan ditolak saat dispatch dengan InvalidArgumentException

Gejala: pembuatan GeneratePdfMessage melemparkan InvalidArgumentException.

Penyebab: objek transfer data (DTO) pada pesan memvalidasi masukannya. Aturan penolakan yang terverifikasi adalah:

• jalur keluaran kosong, atau jalur yang mengandung byte null;
• skema stream-wrapper (misalnya php://...);
• segmen path-traversal .. (pemisah POSIX atau Windows);
• jalur keluaran yang tidak berakhiran .pdf (tidak peka huruf besar/kecil);
• nilai builderClass yang bukan nama kelas yang valid secara sintaksis.

Solusi: berikan jalur sistem berkas absolut yang berakhiran .pdf dan nama kelas builder yang benar dan terkualifikasi penuh.

Sebuah dokumen membawa data usang

Gejala: PDF yang dihasilkan menyertakan konten dari permintaan sebelumnya.

Penyebab: worker yang berjalan lama menahan satu instance Document lintas permintaan. Layanan dokumen bersifat non-shared justru untuk mencegah hal ini.

Solusi: panggil PdfFactory::create() di dalam metode yang berada dalam cakupan permintaan. Jangan pernah menyimpan dokumen yang dikembalikan di layanan bersama.

Referensi perintah diagnostik

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

Konformitas

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

Spec	Klausa	reference_id	Klaim
PSR-11	psr_11_container#1.1.2.p4		Kontrak pengidentifikasi has()/get() Container

Lihat juga

• /integrations/symfony/install/ — pemasangan dan pendaftaran.
• /integrations/symfony/configuration/ — skema lengkap dan batasan.
• /integrations/symfony/boot-and-discovery/ — urutan penemuan dan boot.
• /integrations/symfony/security-and-operations/ — header keamanan dan validasi jalur.