Khắc phục sự cố NextPDF trong CodeIgniter 4

Tổng quan nhanh

Mỗi triệu chứng bên dưới đều tương ứng với một nguyên nhân đã được xác minh trong mã nguồn của gói hoặc framework, kèm theo cách khắc phục cụ thể.

Khám phá và phân giải

`Services::pdfDocument()` trả về `null`

Khi CodeIgniter phân giải một service, nó quét các lớp Config\Services đã khám phá để tìm phương thức phù hợp. Giá trị trả về null nghĩa là CodeIgniter chưa khám phá được lớp Services của gói.

Hãy kiểm tra các nguyên nhân và cách khắc phục sau:

Tính năng tự động khám phá bị tắt. Ứng dụng host có thể đã đặt Config\Modules::$discoverInComposer = false. Nếu vậy, hãy thêm nextpdf/codeigniter vào $composerPackages['only']. CodeIgniter chỉ quét các gói Composer khi cờ này là true.
Autoloader đã lỗi thời. Composer ánh xạ tiền tố namespace NextPDF\CodeIgniter\ đến thư mục gốc tương ứng. Một classmap lỗi thời sẽ che giấu lớp đó (PSR-4 §x1.x3). Hãy chạy composer dump-autoload.
Danh sách $aliases đã bị rút gọn. Việc khám phá chỉ chạy cho các mục trong Config\Modules::$aliases. Gói này cần services và, đối với helper, registrars. Hãy khôi phục cả hai mục.

`pdf()` hoặc `pdf_document()` không được định nghĩa

Các helper được nạp qua hai đường: mục autoload files trong Composer của gói và Registrar của gói. Lỗi hàm chưa được định nghĩa nghĩa là mục files chưa được nạp.

Hãy chạy composer dump-autoload để dựng lại danh sách autoload files.
Hãy xác nhận rằng nextpdf/codeigniter xuất hiện trong vendor/composer/autoload_files.php.
Nếu bạn cần một giải pháp tạm thời, hãy gọi trực tiếp Services::pdf(false) hoặc Services::pdfDocument(false). Các helper chỉ là wrapper mỏng quanh những lệnh gọi này.

Cấu hình

`.env` — các giá trị ghi đè bị bỏ qua

Để phân giải một giá trị ghi đè, BaseConfig dùng tên lớp ngắn ở dạng chữ thường làm tiền tố. Vì lớp này là NextPdf, tiền tố là nextpdf. Không phải nextPdf hay NextPdf.

Hãy dùng nextpdf.fontsPath, không phải nextPdf.fontsPath.
Với khóa lồng nhau, hãy dùng dấu chấm: nextpdf.signature.certificate.
Dạng đầy đủ NextPDF\CodeIgniter\Config\NextPdf.fontsPath cũng dùng được.

Toàn bộ mảng cấu hình quay về giá trị mặc định

Khi bạn mở rộng lớp NextPdf và gán một mảng chỉ gồm một phần, CodeIgniter sẽ thay thế toàn bộ mảng. Hãy cung cấp mọi khóa trong mảng mà bạn ghi đè. Để xem ví dụ mảng đầy đủ, hãy tham khảo /integrations/codeigniter/configuration/.

Lỗi thời gian chạy

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

Sổ đăng ký phông chữ kiểm tra mbstring và zlib một lần cho mỗi tiến trình. Nó phát sinh lỗi này kèm theo tên extension còn thiếu. Hãy cài đặt hoặc bật extension được nêu tên trong runtime PHP, rồi khởi động lại worker hoặc pool PHP FastCGI Process Manager (PHP-FPM).

`RuntimeException: NextPdf fontsPath contains invalid characters`

Sổ đăng ký phông chữ từ chối fontsPath có chứa stream wrapper (://) hoặc null byte. Hãy đặt fontsPath thành một đường dẫn hệ thống tệp thông thường. Đừng trỏ nó tới đường dẫn được bọc kiểu php://, phar://, hoặc tương tự.

Sự cố phản hồi

Tên tệp trông sai trong bản tải xuống

PdfResponse làm sạch tên tệp. Hãy dự kiến các hành vi đã được xác minh sau:

Tên tệp rỗng hoặc chỉ chứa khoảng trắng sẽ trở thành document.pdf.
Tên không có phần mở rộng .pdf (hoặc .PDF) sẽ được nối thêm .pdf. Phần mở rộng .PDF đã có sẵn sẽ được giữ nguyên.
Tên có ký tự không phải ASCII sẽ tạo ra một phương án dự phòng ASCII và tham số RFC 5987 filename*=UTF-8''…, nhờ đó các trình duyệt hiện đại hiển thị tên gốc. Đây là hành vi mong đợi, không phải lỗi.
Dấu phân tách đường dẫn, null byte và ký tự xuống dòng return/line feed (CR/LF) đều bị loại bỏ.

Phản hồi thiếu header bảo mật

Mỗi PdfResponse đều bao gồm X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, X-Robots-Tag, và Referrer-Policy. Nếu chúng vắng mặt ở phía client, nghĩa là một proxy hoặc ứng dụng phía sau đang loại bỏ hoặc ghi đè chúng. Hãy kiểm tra phản hồi cả trước và sau reverse proxy của bạn.

Hàng đợi

`QueueException` khi đẩy job

Hàng đợi đối chiếu tên job được đẩy với các khóa trong Config\Queue::$jobHandlers và từ chối mọi tên chưa được đăng ký. Hãy đăng ký job dưới một khóa tên, rồi đẩy chính tên đó:

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

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

Việc đẩy GeneratePdfJob::class làm tên job sẽ thất bại. Đối số thứ hai là khóa tên, không phải chuỗi tên lớp.

`InvalidArgumentException` từ job

Job xác thực payload trước khi thực hiện bất kỳ công việc nào. Các trường hợp từ chối đã được xác minh sau sẽ trả về các đoạn thông báo này:

Nguyên nhân	Đoạn thông báo
`builder` bị thiếu, rỗng, hoặc không phải chuỗi	`non-empty static callable string`
`builder` nằm ngoài `App\PdfBuilders`	`not allowed`
`builder` khớp với mẫu nhưng không thể gọi được	`not a valid callable`
`outputPath` bị thiếu hoặc rỗng	`non-empty string`
`outputPath` nằm ngoài `WRITEPATH/pdfs/`	`outside of allowed directory`
`outputPath` không kết thúc bằng `.pdf`	`must end with .pdf`

Hãy sửa payload để builder là một static callable App\PdfBuilders\<Class>::<method>. Hãy bảo đảm đường dẫn đầu ra sau khi phân giải nằm trong WRITEPATH/pdfs/ và có phần mở rộng .pdf.

`class … BaseJob not found`

Vì codeigniter4/queue là phụ thuộc chỉ dành cho môi trường phát triển của gói, ứng dụng chạy worker phải yêu cầu trực tiếp phụ thuộc này:

composer require codeigniter4/queue

Chẩn đoán

composer show nextpdf/codeigniter — xác nhận Composer đã phân giải gói.
composer dump-autoload — dựng lại cơ chế khám phá và danh sách autoload của helper.
php spark routes — xác nhận các route PDF của bạn đã được đăng ký.
Để kiểm tra việc khám phá nhanh nhất, hãy dùng một controller gọi Services::pdfDocument(false) và xác nhận kết quả là một Document.

Tuân thủ

Ánh xạ lớp tới đường dẫn — liên quan đến các lỗi khám phá (PSR-4 Autoloader §x1.x3).

Xem thêm

/integrations/codeigniter/install/ — các yêu cầu cho việc khám phá.
/integrations/codeigniter/configuration/ — tiền tố .env và quy tắc ghi đè mảng.
/integrations/codeigniter/production-usage/ — cách đăng ký hàng đợi đúng.
/integrations/codeigniter/boot-and-discovery/ — trình tự khám phá.