Обзор интеграции NextPDF с Symfony

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

nextpdf/symfony — официальный бандл Symfony 7 для движка NextPDF. Он подключает движок к контейнеру Symfony и предоставляет фабрику документов, которую можно внедрять в собственные сервисы. В бандл также входят помощники для формирования ответов Hypertext Transfer Protocol (HTTP) и механизм асинхронной генерации файлов Portable Document Format (PDF), чтобы работа могла выполняться в фоновом режиме.

Что предоставляет бандл

NextPDF Symfony встраивает движок nextpdf/core в приложение Symfony как стандартный бандл. Он добавляет следующие строительные блоки; каждый из них сверен с исходным кодом бандла в src/Symfony/:

Точка входа бандла — NextPDF\Symfony\NextPdfBundle расширяет базовый класс Symfony Bundle и регистрирует один compiler pass.
Расширение для внедрения зависимостей — NextPDF\Symfony\DependencyInjection\NextPdfExtension загружает определения сервисов, преобразует дерево конфигурации в параметры контейнера и задаёт псевдоним конфигурации nextpdf.
Типизированное дерево конфигурации — NextPDF\Symfony\DependencyInjection\Configuration определяет схему конфигурации nextpdf. Оно проверяет значения enum, задаёт значения по умолчанию и использует плейсхолдеры %kernel.*%.
Внедряемая фабрика документов — NextPDF\Symfony\Service\PdfFactory создаёт новые предварительно настроенные экземпляры NextPDF\Core\Document. В Symfony это аналог статического фасада.
Помощники для HTTP-ответов — NextPDF\Symfony\Http\PdfResponse формирует inline-, download- и streaming-ответы с фиксированным набором заголовков безопасности, согласованных с рекомендациями Open Worldwide Application Security Project (OWASP).
Путь асинхронной генерации — NextPDF\Symfony\Message\GeneratePdfMessage, NextPDF\Symfony\Message\GeneratePdfHandler и NextPDF\Symfony\Message\PdfBuilderInterface интегрируются с Symfony Messenger, чтобы отрисовка PDF выполнялась в обработчике.
Детектор расширений на этапе компиляции — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass обнаруживает опциональные расширения NextPDF и регистрирует их сервисы только при наличии этих расширений.

Контракт контейнера

Бандл регистрирует небольшой стабильный набор публичных сервисов контейнера. Сервис документа nextpdf.document (с псевдонимами NextPDF\Contracts\PdfDocumentInterface и NextPDF\Core\Document) не является общим: при каждом разрешении контейнер возвращает отдельный одноразовый документ. Это соответствует контракту контейнера PHP Standard Recommendation 11 (PSR-11): два последовательных вызова get() с одним и тем же идентификатором могут возвращать разные значения в зависимости от конфигурации контейнера; см. PSR-11 §1.1.2. Привязка без совместного использования выбрана намеренно. Документ накапливает состояние конкретной отрисовки, поэтому новый экземпляр для каждого запроса предотвращает утечку состояния между запросами в долгоживущих обработчиках.

Реестр шрифтов (NextPDF\Contracts\FontRegistryInterface) работает иначе: это общий singleton. Реестр изображений помечен тегом kernel.reset, поэтому его ограниченный кэш очищается между запросами в обработчиках FrankenPHP и Messenger. Полная таблица сервисов и псевдонимов приведена на странице конфигурации.

Опциональное логирование

Реестры шрифтов и изображений принимают опциональный логгер PHP Standard Recommendation 3 (PSR-3). Бандл привязывает Psr\Log\LoggerInterface только если приложение предоставляет этот интерфейс (nullOnInvalid()). Поэтому логирование остаётся опциональным компонентом, а не жёсткой зависимостью. Это соответствует контракту логгера PSR-3, где логгер рассматривается как внедряемый заменяемый компонент (PSR-3).

Базовые и опциональные возможности

Сам бандл относится к базовому программному обеспечению под лицензией Apache-2.0. Некоторые возможности появляются только при установке опционального пакета вместе с бандлом:

Возможность	Требует	Обнаружение
Генерация PDF, `PdfFactory`, `PdfResponse`	только базовая версия	доступна всегда
Асинхронная генерация	`symfony/messenger`	обработчик активируется, когда установлен Messenger
Отрисовка HTML через Chrome DevTools Protocol (CDP)	`nextpdf/artisan`	проверка `class_exists` на этапе компиляции
Архивация PDF/A, цифровые подписи	`nextpdf/premium` (устанавливает Pro)	проверка `class_exists` на этапе компиляции

Когда установлен nextpdf/premium, бандл может применить базовую конфигурацию подписи PDF Advanced Electronic Signatures (PAdES) B-B. Более высокие профили подписи выходят за рамки документации этого бандла. Матрицу выпусков см. в документации NextPDF Premium.

Когда использовать этот бандл

Используйте nextpdf/symfony, когда создаёте PDF внутри HTTP-приложения или обработчика Symfony 7. Бандл предоставляет управляемые контейнером сервисы, безопасные для обработчиков реестры и защищённые ответы для загрузки, поэтому подключать движок вручную не нужно. Если нужна только разовая генерация в скрипте, достаточно одного базового пакета nextpdf/core.

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

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

Спецификация	Пункт	Идентификатор источника (reference_id)	Утверждение
PSR-11	`psr_11_container#1.1.2.p3.b`		Контракт возвращаемого значения get() контейнера
PSR-3	`psr_3_logger#x3.p17`		Опциональная зависимость LoggerInterface

Коммерческий контекст

Цифровые подписи и архивация PDF/A становятся доступны, когда nextpdf/premium (Pro) установлен вместе с бандлом. Эта опциональная возможность Pro не требует менять код в описанном здесь бандле Core. См. </get-license/?intent=symfony-pro>.

См. также

/integrations/symfony/install/ — установка и регистрация бандла.
/integrations/symfony/configuration/ — полное дерево конфигурации nextpdf и таблица сервисов.
/integrations/symfony/quickstart/ — готовый к запуску контроллер и пример асинхронной работы.
/integrations/symfony/boot-and-discovery/ — как Symfony обнаруживает и загружает бандл.
/integrations/symfony/production-usage/ — безопасность обработчиков, потоковая передача и асинхронные паттерны.