Pemecahan Masalah NextPDF di CodeIgniter 4

Sekilas

Setiap gejala di bawah ini dipetakan ke penyebab yang terverifikasi pada sumber paket atau framework, serta disertai perbaikan konkret.

Discovery dan resolusi

`Services::pdfDocument()` mengembalikan `null`

Saat CodeIgniter me-resolve sebuah service, CodeIgniter memindai kelas Config\Services yang ditemukan untuk mencari metode yang cocok. Nilai balik null berarti CodeIgniter tidak menemukan kelas Services milik paket.

Periksa penyebab dan perbaikan berikut:

Auto-discovery dinonaktifkan. Aplikasi host mungkin menyetel Config\Modules::$discoverInComposer = false. Jika demikian, tambahkan nextpdf/codeigniter ke $composerPackages['only']. CodeIgniter hanya memindai paket Composer ketika flag ini bernilai true.
Autoloader sudah usang. Composer memetakan prefiks namespace NextPDF\CodeIgniter\ ke direktori dasarnya. Classmap yang tidak mutakhir membuat kelas tersebut tidak terlihat (PSR-4 §x1.x3). Jalankan composer dump-autoload.
Daftar $aliases dipangkas. Discovery hanya berjalan untuk entri di Config\Modules::$aliases. Paket ini membutuhkan services, dan untuk helper, registrars. Pulihkan kedua entri tersebut.

`pdf()` atau `pdf_document()` tidak terdefinisi

Helper dimuat melalui dua jalur: entri autoload Composer files milik paket dan Registrar paket. Galat fungsi yang tidak terdefinisi berarti entri files tidak dimuat.

Jalankan composer dump-autoload untuk membangun ulang daftar autoload files.
Pastikan nextpdf/codeigniter muncul di vendor/composer/autoload_files.php.
Jika Anda memerlukan solusi sementara, panggil Services::pdf(false) atau Services::pdfDocument(false) secara langsung. Helper hanya pembungkus tipis untuk panggilan tersebut.

Konfigurasi

Override `.env` diabaikan

Untuk me-resolve sebuah override, BaseConfig menggunakan nama kelas singkat dalam huruf kecil sebagai prefiks. Karena kelasnya adalah NextPdf, prefiksnya adalah nextpdf, bukan nextPdf atau NextPdf.

Gunakan nextpdf.fontsPath, bukan nextPdf.fontsPath.
Untuk kunci bertingkat, gunakan titik: nextpdf.signature.certificate.
Bentuk fully qualified NextPDF\CodeIgniter\Config\NextPdf.fontsPath juga berlaku.

Seluruh array konfigurasi kembali ke nilai standar

Ketika Anda memperluas kelas NextPdf dan menetapkan array parsial, CodeIgniter mengganti seluruh array. Sediakan setiap kunci dalam array yang Anda override. Untuk contoh array lengkap, lihat /integrations/codeigniter/configuration/.

Galat runtime

`RuntimeException: NextPDF requires the ext-… PHP extension`

Font registry memvalidasi mbstring dan zlib sekali per proses. Registry ini memunculkan galat tersebut beserta nama ekstensi yang hilang. Pasang atau aktifkan ekstensi yang disebutkan pada PHP runtime, lalu mulai ulang worker atau pool PHP FastCGI Process Manager (PHP-FPM).

`RuntimeException: NextPdf fontsPath contains invalid characters`

Font registry menolak fontsPath yang mengandung stream wrapper (://) atau null byte. Setel fontsPath ke path sistem berkas biasa. Jangan arahkan ke path yang dibungkus dengan php://, phar://, atau sejenisnya.

Masalah respons

Nama berkas tampak salah saat diunduh

PdfResponse membersihkan nama berkas. Perilaku terverifikasi yang diharapkan adalah sebagai berikut:

Nama berkas yang kosong atau hanya berisi spasi menjadi document.pdf.
Nama tanpa ekstensi .pdf (atau .PDF) akan mendapat tambahan .pdf. .PDF yang sudah ada dipertahankan apa adanya.
Nama dengan karakter non-ASCII menghasilkan fallback ASCII dan parameter RFC 5987 filename*=UTF-8''…, sehingga peramban modern menampilkan nama aslinya. Ini adalah perilaku yang diharapkan, bukan bug.
Pemisah path, null byte, dan carriage return/line feed (CR/LF) dihapus.

Respons kehilangan header keamanan

Setiap PdfResponse menyertakan X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, X-Robots-Tag, dan Referrer-Policy. Jika header tersebut tidak ada di sisi klien, berarti ada proxy atau aplikasi yang menghapus atau menimpanya di hilir. Periksa respons, baik sebelum maupun setelah reverse proxy Anda.

Antrean

`QueueException` saat mendorong job

Antrean membandingkan nama job yang didorong dengan kunci di Config\Queue::$jobHandlers dan menolak nama apa pun yang tidak terdaftar. Daftarkan job di bawah kunci nama, lalu dorong nama tersebut:

public array $jobHandlers = ['generate-pdf' => GeneratePdfJob::class];

// dispatch
\service('queue')->push('pdf-queue', 'generate-pdf', [...]);

Mendorong GeneratePdfJob::class sebagai nama job akan gagal. Argumen kedua adalah kunci nama, bukan string kelas.

`InvalidArgumentException` dari job

Job memvalidasi payload-nya sebelum melakukan pekerjaan apa pun. Kasus penolakan terverifikasi berikut mengembalikan fragmen pesan berikut:

Penyebab	Fragmen pesan
`builder` hilang, kosong, atau bukan string	`non-empty static callable string`
`builder` di luar `App\PdfBuilders`	`not allowed`
`builder` cocok dengan pola tetapi tidak callable	`not a valid callable`
`outputPath` hilang atau kosong	`non-empty string`
`outputPath` di luar `WRITEPATH/pdfs/`	`outside of allowed directory`
`outputPath` tidak berakhiran `.pdf`	`must end with .pdf`

Perbaiki payload agar builder berupa static callable App\PdfBuilders\<Class>::<method>. Pastikan hasil resolve path keluaran berada di dalam WRITEPATH/pdfs/ dengan ekstensi .pdf.

`class … BaseJob not found`

Karena codeigniter4/queue merupakan dependensi khusus pengembangan paket ini, aplikasi yang menjalankan worker harus me-require paket tersebut secara langsung:

composer require codeigniter4/queue

Diagnostik

composer show nextpdf/codeigniter — pastikan Composer berhasil me-resolve paket tersebut.
composer dump-autoload — bangun ulang discovery dan daftar autoload helper.
php spark routes — pastikan rute PDF Anda terdaftar.
Untuk pengecekan discovery tercepat, gunakan controller yang memanggil Services::pdfDocument(false) dan memastikan hasilnya adalah Document.

Konformansi

Pemetaan kelas-ke-path — relevan dengan kegagalan discovery (PSR-4 Autoloader §x1.x3).

Lihat juga

/integrations/codeigniter/install/ — persyaratan untuk discovery.
/integrations/codeigniter/configuration/ — prefiks .env dan aturan override array.
/integrations/codeigniter/production-usage/ — registrasi antrean yang benar.
/integrations/codeigniter/boot-and-discovery/ — urutan discovery.