Устранение неполадок NextPDF в CodeIgniter 4

Кратко

Для каждого симптома ниже указана причина, проверенная по исходному коду пакета или фреймворка, и конкретный способ устранения.

Обнаружение и разрешение

`Services::pdfDocument()` возвращает `null`

При разрешении сервиса CodeIgniter просматривает обнаруженные классы Config\Services и ищет подходящий метод. Если возвращается null, значит CodeIgniter не обнаружил класс Services пакета.

Проверьте следующие причины и способы устранения:

Автообнаружение отключено. В основном приложении может быть задано Config\Modules::$discoverInComposer = false. В этом случае добавьте nextpdf/codeigniter в $composerPackages['only']. CodeIgniter просматривает пакеты Composer только тогда, когда этот флаг равен true.
Автозагрузчик устарел. Composer сопоставляет префикс пространства имён NextPDF\CodeIgniter\ с его базовым каталогом. Устаревшая карта классов может скрыть класс (PSR-4 §x1.x3). Выполните composer dump-autoload.
Список $aliases сокращён. Обнаружение выполняется только для записей в Config\Modules::$aliases. Пакету требуется services, а для хелперов — registrars. Восстановите обе записи.

`pdf()` или `pdf_document()` не определены

Хелперы загружаются двумя способами: через запись автозагрузки Composer files пакета и через Registrar пакета. Ошибка о неопределённой функции означает, что запись files не загрузилась.

Выполните composer dump-autoload, чтобы перестроить список автозагрузки files.
Убедитесь, что nextpdf/codeigniter присутствует в vendor/composer/autoload_files.php.
Если требуется обходное решение, вызовите Services::pdf(false) или Services::pdfDocument(false) напрямую. Хелперы представляют собой тонкие обёртки вокруг этих вызовов.

Конфигурация

`.env` — переопределения игнорируются

При разрешении переопределений BaseConfig использует в качестве префикса короткое имя класса в нижнем регистре. Поскольку класс называется NextPdf, префикс — nextpdf. Это не nextPdf и не NextPdf.

Используйте nextpdf.fontsPath, а не nextPdf.fontsPath.
Для вложенного ключа используйте точку: nextpdf.signature.certificate.
Полностью квалифицированная форма NextPDF\CodeIgniter\Config\NextPdf.fontsPath также работает.

Весь массив конфигурации сбрасывается к значениям по умолчанию

Когда вы расширяете класс NextPdf и задаёте неполный массив, CodeIgniter заменяет весь массив целиком. Указывайте каждый ключ в переопределяемом массиве. Пример полного массива см. в /integrations/codeigniter/configuration/.

Ошибки времени выполнения

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

Реестр шрифтов проверяет mbstring и zlib один раз в рамках процесса. Если расширение отсутствует, возникает эта ошибка с его именем. Установите или включите указанное расширение в исполняемой среде PHP, затем перезапустите воркер или пул PHP FastCGI Process Manager (PHP-FPM).

`RuntimeException: NextPdf fontsPath contains invalid characters`

Реестр шрифтов отклоняет fontsPath, содержащий обёртку потока (://) или нулевой байт. Задайте fontsPath как обычный путь в файловой системе. Не задавайте для него путь php://, phar:// или аналогичный путь с обёрткой.

Проблемы с ответом

Имя файла при скачивании выглядит неправильно

PdfResponse очищает имена файлов. Ожидайте следующее проверенное поведение:

Пустое имя файла или имя из одних пробелов становится document.pdf.
К имени без расширения .pdf (или .PDF) добавляется .pdf. Существующее .PDF сохраняется как есть.
Для имени с символами за пределами ASCII формируется резервный вариант в ASCII и параметр RFC 5987 filename*=UTF-8''…, поэтому современные браузеры показывают исходное имя. Это ожидаемое поведение, а не ошибка.
Разделители пути, нулевые байты и символы возврата каретки и перевода строки (CR/LF) удаляются.

В ответе отсутствуют заголовки безопасности

Каждый PdfResponse включает X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, X-Robots-Tag и Referrer-Policy. Если на стороне клиента они отсутствуют, значит прокси или приложение удаляет либо перезаписывает их дальше по цепочке. Проверьте ответ как до, так и после обратного прокси.

Очередь

`QueueException` при постановке задания в очередь

Очередь сверяет имя отправляемого задания с ключами в Config\Queue::$jobHandlers и отклоняет любое незарегистрированное имя. Зарегистрируйте задание под нужным ключом, затем ставьте в очередь именно это имя:

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

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

Если поставить GeneratePdfJob::class в качестве имени задания, это завершится ошибкой. Второй аргумент — это ключ-имя, а не строка с именем класса.

`InvalidArgumentException` от задания

Задание проверяет свою полезную нагрузку, прежде чем приступить к работе. Для этих проверяемых отказов возвращаются следующие фрагменты сообщений:

Причина	Фрагмент сообщения
`builder` отсутствует, пуст или не является строкой	`non-empty static callable string`
`builder` вне `App\PdfBuilders`	`not allowed`
`builder` соответствует шаблону, но не является вызываемым	`not a valid callable`
`outputPath` отсутствует или пуст	`non-empty string`
`outputPath` вне `WRITEPATH/pdfs/`	`outside of allowed directory`
`outputPath` не заканчивается на `.pdf`	`must end with .pdf`

Исправьте полезную нагрузку так, чтобы builder был статическим вызываемым App\PdfBuilders\<Class>::<method>. Убедитесь, что выходной путь разрешается внутри WRITEPATH/pdfs/ и имеет расширение .pdf.

`class … BaseJob not found`

Поскольку codeigniter4/queue является dev-зависимостью пакета, приложение, запускающее воркеры, должно подключить её напрямую:

composer require codeigniter4/queue

Диагностика

composer show nextpdf/codeigniter — убедитесь, что Composer разрешает пакет.
composer dump-autoload — обновите обнаружение и список автозагрузки хелперов.
php spark routes — убедитесь, что ваши маршруты PDF зарегистрированы.
Для самой быстрой проверки обнаружения используйте контроллер, который вызывает Services::pdfDocument(false) и проверяет, что результат является Document.

Соответствие

Сопоставление класса с путём относится к сбоям обнаружения (PSR-4 Autoloader §x1.x3).

См. также

/integrations/codeigniter/install/ — требования к обнаружению.
/integrations/codeigniter/configuration/ — префикс .env и правило переопределения массива.
/integrations/codeigniter/production-usage/ — правильная регистрация в очереди.
/integrations/codeigniter/boot-and-discovery/ — последовательность обнаружения.