Устранение неполадок пакета NextPDF для Symfony

Краткий обзор

Большинство проблем относится к одной из четырёх областей: обнаружению, проверке конфигурации, подключению контейнера или маршрутизации Messenger. В каждом разделе симптом сопоставлен с поведением пакета, которое лежит в основе проблемы, а затем приведена консольная команда для проверки исправления.

Пакет не зарегистрирован

Симптом: не удаётся автоматически внедрить PdfFactory, либо debug:container nextpdf ничего не возвращает.

Причина: пакет не добавлен в config/bundles.php. Возможно, Flex не запускался или приложение не использует Flex.

Решение:

php bin/console debug:container nextpdf

Если команда не возвращает ни одной службы, добавьте пакет вручную:

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

В composer.json пакета есть подсказка для автоматической регистрации в разделе extra.symfony.bundles. Она применяется только к приложениям с поддержкой Flex.

Загрузка завершается ошибкой из-за отсутствующего расширения PHP

Симптом: при загрузке ядро выбрасывает RuntimeException с упоминанием ext-mbstring или ext-zlib.

Причина: это срабатывает NextPdfExtension::guardRequiredExtensions() — преднамеренная защита пакета с быстрым отказом. Это не дефект.

Решение: включите указанное расширение в php.ini, затем перезапустите среду выполнения. Проверьте результат командой:

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

Конфигурация отклоняется на этапе сборки

Симптом: Symfony выбрасывает Symfony\Component\Config\Definition\Exception\InvalidConfigurationException во время выполнения cache:clear или cache:warmup.

Причина: значение не соответствует ограничениям схемы. Файл Configuration.php определяет следующие ограничения:

page_format должен быть одним из значений: A4, A3, A5, Letter, Legal, Tabloid.
orientation должен быть P или L.
unit должен быть одним из значений: pt, mm, cm, in.
pdfa должен быть null, 4, 4e или 4f.
image_cache_mb должен быть >= 0.

Решение: выведите итоговую конфигурацию, затем исправьте ключ, который вызвал ошибку:

php bin/console debug:config nextpdf

PDF/A или подписание не действует

Симптом: задан раздел pdfa или signature, но на выходе получается обычный файл Portable Document Format (PDF).

Причина: эти возможности требуют nextpdf/premium. На этапе компиляции PdfFactory применяет PDF/A только при обнаружении расширения Pro. Проход компилятора регистрирует компонент подписания только тогда, когда signature.enabled имеет значение true и задан signature.certificate.

Решение: убедитесь, что Premium установлен и служба компонента подписания существует:

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

Если Premium отсутствует, пакет сохраняет конфигурацию, но намеренно оставляет её неактивной. Задокументированная в Pro возможность подписания ограничена базовым профилем B-B. Документация NextPDF Premium описывает профили помимо B-B.

Отрисовка через Chrome не работает

Симптом: конфигурация artisan игнорируется.

Причина: отрисовка через Chrome DevTools Protocol (CDP) требует nextpdf/artisan. Проход компилятора проверяет его наличие через class_exists на этапе компиляции. Если расширение отсутствует, средство отрисовки не подключается.

Решение:

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

Проверка выполняется во время компиляции контейнера. После установки расширения повторно выполните cache:clear.

Обработчик Messenger ни разу не вызывается

Симптом: вы отправляете GeneratePdfMessage, но PDF не записывается.

Причины и решения:

Сообщение не маршрутизируется — добавьте запись маршрутизации, которая сопоставляет NextPDF\Symfony\Message\GeneratePdfMessage с транспортом в config/packages/messenger.yaml, затем запустите рабочий процесс (php bin/console messenger:consume <transport>).
Построитель отсутствует в локаторе — обработчик получает построитель из локатора PHP Standards Recommendation 11 (PSR-11) по его идентификатору в виде строки имени класса. Идентификатор контейнера — это строка, однозначно идентифицирующая запись (PSR-11, §1.1.2). Если класс построителя не зарегистрирован в локаторе, обработчик выбрасывает RuntimeException с сообщением о том, что настроенный построитель должен реализовывать PdfBuilderInterface. Зарегистрируйте построитель, затем сошлитесь на него из локатора.

Проверьте маршрутизацию и локатор:

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

Сообщение отклоняется при отправке с InvalidArgumentException

Симптом: при создании GeneratePdfMessage выбрасывается InvalidArgumentException.

Причина: объект передачи данных (DTO) сообщения проверяет входные данные. Правила отклонения таковы:

пустой путь вывода или путь, содержащий нулевой байт;
схема обёртки потока (например, php://...);
сегмент обхода каталогов .. (с разделителями POSIX или Windows);
путь вывода, не оканчивающийся на .pdf (без учёта регистра);
значение builderClass, не являющееся синтаксически корректным именем класса.

Решение: передайте абсолютный путь в файловой системе, оканчивающийся на .pdf, и существующее полностью квалифицированное имя класса построителя.

Документ содержит устаревшие данные

Симптом: сформированный PDF содержит контент из предыдущего запроса.

Причина: долгоживущий рабочий процесс удерживал экземпляр Document между запросами. Служба документа сделана необщей именно для того, чтобы предотвратить это.

Решение: вызывайте PdfFactory::create() внутри метода, работающего в области запроса. Никогда не сохраняйте возвращённый документ в общей службе.

Справочник диагностических команд

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

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

Каждая строка содержит нормативное утверждение, сделанное на этой странице, и привязана к полному 64-символьному шестнадцатеричному reference_id из закрытого корпуса организации по разработке стандартов (SDO). Данные о происхождении, включая манифест корпуса и транспорт извлечения, указаны в _sidecars/rag-citations.yaml.

Стандарт	Пункт	reference_id (идентификатор ссылки)	Утверждение
PSR-11	`psr_11_container#1.1.2.p4`		Контракт идентификатора контейнера для has()/get()

См. также

/integrations/symfony/install/ — установка и регистрация.
/integrations/symfony/configuration/ — полная схема и ограничения.
/integrations/symfony/boot-and-discovery/ — обнаружение и последовательность загрузки.
/integrations/symfony/security-and-operations/ — заголовки безопасности и проверка путей.