Rozwiązywanie problemów z NextPDF w CodeIgniter 4

W skrócie

Każdemu z poniższych objawów odpowiada zweryfikowana przyczyna w kodzie źródłowym pakietu lub frameworka oraz konkretne rozwiązanie.

Wykrywanie i rozwiązywanie usług

Metoda `Services::pdfDocument()` zwraca `null`

Gdy CodeIgniter rozwiązuje usługę, przeszukuje wykryte klasy Config\Services w poszukiwaniu pasującej metody. Zwrócenie wartości null oznacza, że CodeIgniter nie wykrył klasy Services należącej do pakietu.

Sprawdź następujące przyczyny i rozwiązania:

Automatyczne wykrywanie jest wyłączone. Aplikacja hostująca może mieć ustawione Config\Modules::$discoverInComposer = false. W takim przypadku dodaj nextpdf/codeigniter do $composerPackages['only']. CodeIgniter przeszukuje pakiety Composera tylko wtedy, gdy ta flaga ma wartość true.
Autoloader jest nieaktualny. Composer mapuje prefiks przestrzeni nazw NextPDF\CodeIgniter\ na katalog bazowy pakietu. Nieaktualna mapa klas sprawia, że klasa nie jest widoczna (PSR-4 §x1.x3). Uruchom composer dump-autoload.
Lista $aliases została skrócona. Wykrywanie działa tylko dla wpisów w Config\Modules::$aliases. Pakiet wymaga wpisu services, a w przypadku funkcji pomocniczych również registrars. Przywróć oba wpisy.

Funkcja `pdf()` lub `pdf_document()` jest niezdefiniowana

Funkcje pomocnicze są ładowane na dwa sposoby: przez należący do pakietu wpis autoładowania files w Composerze oraz przez klasę Registrar pakietu. Błąd niezdefiniowanej funkcji oznacza, że wpis files nie został załadowany.

Uruchom composer dump-autoload, aby odbudować listę autoładowania files.
Sprawdź, czy nextpdf/codeigniter znajduje się w vendor/composer/autoload_files.php.
Jeśli potrzebne jest rozwiązanie zastępcze, wywołaj bezpośrednio Services::pdf(false) lub Services::pdfDocument(false). Funkcje pomocnicze to lekkie nakładki na te wywołania.

Konfiguracja

Nadpisania z pliku `.env` są ignorowane

Aby wykryć nadpisanie, BaseConfig używa jako prefiksu krótkiej nazwy klasy zapisanej małymi literami. Ponieważ klasa nosi nazwę NextPdf, prefiksem jest nextpdf. Nie jest nim nextPdf ani NextPdf.

Użyj nextpdf.fontsPath, a nie nextPdf.fontsPath.
W przypadku klucza zagnieżdżonego użyj kropki: nextpdf.signature.certificate.
Działa również w pełni kwalifikowana forma NextPDF\CodeIgniter\Config\NextPdf.fontsPath.

Cała tablica konfiguracji wraca do wartości domyślnych

Gdy rozszerzasz klasę NextPdf i przypisujesz częściową tablicę, CodeIgniter zastępuje całą tablicę. Podaj każdy klucz w nadpisywanej tablicy. Przykład pełnej tablicy znajduje się w /integrations/codeigniter/configuration/.

Błędy w czasie wykonywania

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

Rejestr czcionek sprawdza rozszerzenia mbstring i zlib raz na proces. Zgłasza ten błąd, podając nazwę brakującego rozszerzenia. Zainstaluj lub włącz wskazane rozszerzenie w środowisku uruchomieniowym PHP, a następnie zrestartuj worker lub pulę PHP FastCGI Process Manager (PHP-FPM).

`RuntimeException: NextPdf fontsPath contains invalid characters`

Rejestr czcionek odrzuca fontsPath zawierający wrapper strumienia (://) lub bajt zerowy. Ustaw fontsPath na zwykłą ścieżkę systemu plików. Nie ustawiaj jej na ścieżkę php://, phar:// ani podobną ścieżkę z wrapperem.

Problemy z odpowiedzią

Nazwa pliku w pobieranym dokumencie wygląda niepoprawnie

Klasa PdfResponse oczyszcza nazwy plików. Oczekiwane jest następujące zweryfikowane zachowanie:

Pusta nazwa pliku lub nazwa składająca się wyłącznie z białych znaków zostaje zamieniona na document.pdf.
Do nazwy bez rozszerzenia .pdf (lub .PDF) dopisywane jest .pdf. Istniejące rozszerzenie .PDF jest zachowywane bez zmian.
Dla nazwy zawierającej znaki spoza ASCII generowany jest wariant zapasowy w ASCII oraz parametr RFC 5987 filename*=UTF-8''…, dzięki czemu nowoczesne przeglądarki wyświetlają oryginalną nazwę. Jest to zachowanie oczekiwane, a nie błąd.
Separatory ścieżek, bajty zerowe oraz znaki powrotu karetki i nowego wiersza (return/line feed, CR/LF) są usuwane.

W odpowiedzi brakuje nagłówków bezpieczeństwa

Każda odpowiedź PdfResponse zawiera nagłówki X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, X-Robots-Tag i Referrer-Policy. Jeśli nie docierają do klienta, oznacza to, że proxy lub aplikacja usuwa je albo nadpisuje na dalszym etapie. Sprawdź odpowiedź zarówno przed odwrotnym proxy, jak i za nim.

Kolejka

`QueueException` podczas dodawania zadania do kolejki

Kolejka porównuje nazwę dodawanego zadania z kluczami w Config\Queue::$jobHandlers i odrzuca każdą nazwę, która nie jest zarejestrowana. Zarejestruj zadanie pod kluczem będącym jego nazwą, a następnie dodaj tę nazwę do kolejki:

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

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

Dodanie GeneratePdfJob::class jako nazwy zadania kończy się niepowodzeniem. Drugi argument to klucz nazwy, a nie ciąg znaków z nazwą klasy.

`InvalidArgumentException` zgłaszany przez zadanie

Zadanie sprawdza poprawność swojego ładunku, zanim wykona jakąkolwiek pracę. W następujących zweryfikowanych przypadkach odrzucenia zwracane są podane fragmenty komunikatów:

Przyczyna	Fragment komunikatu
`builder` brakujący, pusty albo niebędący ciągiem znaków	`non-empty static callable string`
`builder` znajduje się poza `App\PdfBuilders`	`not allowed`
`builder` pasuje do wzorca, ale nie jest wywoływalny	`not a valid callable`
`outputPath` brakujący albo pusty	`non-empty string`
`outputPath` znajduje się poza `WRITEPATH/pdfs/`	`outside of allowed directory`
`outputPath` nie kończy się na `.pdf`	`must end with .pdf`

Popraw ładunek tak, aby builder był statycznym elementem wywoływalnym App\PdfBuilders\<Class>::<method>. Upewnij się, że ścieżka wyjściowa wskazuje lokalizację wewnątrz WRITEPATH/pdfs/ i kończy się rozszerzeniem .pdf.

`class … BaseJob not found`

Ponieważ codeigniter4/queue jest zależnością deweloperską pakietu, aplikacja uruchamiająca workery musi dodać ją bezpośrednio do swoich zależności:

composer require codeigniter4/queue

Diagnostyka

composer show nextpdf/codeigniter — potwierdza, że Composer rozwiązał pakiet.
composer dump-autoload — odbudowuje dane wykrywania oraz listę autoładowania funkcji pomocniczych.
php spark routes — potwierdza, że trasy PDF aplikacji są zarejestrowane.
Aby najszybciej sprawdzić wykrywanie, użyj kontrolera, który wywołuje Services::pdfDocument(false) i sprawdza, czy wynik ma typ Document.

Zgodność

Mapowanie klasy na ścieżkę — istotne przy problemach z wykrywaniem (PSR-4 Autoloader §x1.x3).

Zobacz też

/integrations/codeigniter/install/ — wymagania dotyczące wykrywania.
/integrations/codeigniter/configuration/ — prefiks .env oraz reguła nadpisywania tablic.
/integrations/codeigniter/production-usage/ — prawidłowa rejestracja kolejki.
/integrations/codeigniter/boot-and-discovery/ — sekwencja wykrywania.