Загрузка и автообнаружение NextPDF в Symfony

Кратко

Ядро регистрирует NextPdfBundle. DI-расширение бандла загружает services.php и преобразует дерево конфигурации в параметры контейнера. Затем единственный проход компилятора подключает необязательные расширения и настраивает прогрев шрифтов.

Как Symfony Flex подхватывает бандл

В composer.json бандла объявлена подсказка для автоматической регистрации:

{
    "extra": {
        "symfony": {
            "bundles": {
                "NextPDF\\Symfony\\NextPdfBundle": "all"
            }
        }
    }
}

В приложении с Symfony Flex эта подсказка добавляет NextPDF\Symfony\NextPdfBundle в config/bundles.php для всех окружений (all). Без Flex добавьте бандл вручную в config/bundles.php. Модель регистрации бандлов описана в документации Symfony: (https://symfony.com/doc/current/bundles.html). Классы бандла автозагружаются по префиксу PHP Standard Recommendation (PSR)-4 NextPDF\Symfony\, сопоставленному с src/Symfony/. Автозагрузчик PSR-4 сопоставляет префикс пространства имён с этим базовым каталогом (PSR-4 §2).

Последовательность загрузки

Последовательность загрузки сверена с исходным кодом бандла:

1. Ядро регистрирует бандлы. Kernel::registerBundles() читает config/bundles.php и создаёт экземпляр NextPDF\Symfony\NextPdfBundle, который расширяет Symfony\Component\HttpKernel\Bundle\Bundle.
2. Сборка бандла. NextPdfBundle::build() вызывает родительский метод, а затем регистрирует единственный проход компилятора: OptionalExtensionPass. NextPdfBundle::getPath() возвращает корневой каталог пакета.
3. Загрузка расширения. DI-расширение NextPDF\Symfony\DependencyInjection\NextPdfExtension (псевдоним nextpdf) выполняет processConfiguration() по схеме Configuration. Оно записывает разрешённые значения в параметры контейнера nextpdf.*, а затем загружает config/services.php через PhpFileLoader.
4. Проверка обязательных расширений. В конце NextPdfExtension::load() проверяет наличие ext-mbstring и ext-zlib и сразу завершается с ошибкой, если их нет.
5. Выполняется проход компилятора. Во время компиляции контейнера OptionalExtensionPass::process() задаёт флаги доступности расширений в PdfFactory, при необходимости регистрирует подписывающий компонент и клиент службы меток времени (TSA), а также планирует прогрев и блокировку реестра шрифтов.
6. Контейнер скомпилирован и закэширован. Symfony записывает скомпилированный контейнер. cache:warmup выполняет этот шаг до того, как приложение начнёт принимать трафик.

Проходы компилятора

Бандл регистрирует ровно один проход — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass — в NextPdfBundle::build(). Он выполняется в группе проходов по умолчанию (до оптимизации). Этот проход выполняет четыре шага. Каждый защищён проверкой: если входных данных нет, шаг ничего не делает:

• Флаги расширений — добавляет вызовы методов setArtisanAvailable(...) и setProAvailable(...) в определение PdfFactory. Значения берутся из проверок class_exists, выполненных на этапе компиляции, для фабрики браузера Artisan и класса Pro PDF/A.
• Регистрация подписывающего компонента — регистрирует фабрику сведений о сертификате и сервис подписи для базового профиля B-B, когда присутствует nextpdf.signature, значение enabled равно true и задан сертификат.
• Клиент TSA — регистрирует сервис клиента TSA, когда у nextpdf.tsa задан URL.
• Прогрев шрифтов — добавляет вызовы методов warmup() и lock() в определение реестра шрифтов, если nextpdf.preload_fonts не пуст.

Привязки контейнера

config/services.php определяет сервисы. Сервис документа nextpdf.document (с псевдонимами NextPDF\Contracts\PdfDocumentInterface и NextPDF\Core\Document) является не разделяемым: при каждом разрешении возвращается новый документ. PSR-11 прямо допускает такое поведение; последовательные вызовы get() для одного идентификатора могут возвращать разные значения (PSR-11 §1.1.2). Реестр шрифтов разделяемый и блокируется после прогрева. Реестр изображений разделяемый и помечен тегом kernel.reset. Полная таблица приведена в /integrations/symfony/configuration/.

Порядок разрешения конфигурации

1. Встроенные значения по умолчанию из Configuration (getConfigTreeBuilder()).
2. Переопределения приложения в config/packages/nextpdf.yaml и переопределения для окружения в config/packages/<env>/.
3. Symfony разрешает подстановочные параметры %kernel.*%. Например, fonts_path по умолчанию равно %kernel.project_dir%/resources/fonts.
4. NextPdfExtension::load() записывает объединённый результат в параметры контейнера nextpdf.*, которые используют services.php и проход компилятора.

Недопустимые значения приводят к ошибке на шаге 1–2 и вызывают исключение Symfony InvalidConfigurationException.

Диагностика

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console cache:clear

Первая команда выводит список зарегистрированных сервисов. Вторая показывает объединённую конфигурацию. Третья пересобирает контейнер и повторно выполняет проверки расширений на этапе компиляции.

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

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

Спецификация	Раздел	reference_id (идентификатор ссылки)	Утверждение
PSR-11	psr_11_container#1.1.2.p3.b		Разрешение контейнера может различаться при каждом вызове
PSR-4	psr_4_autoload#x1.x2.p5		Сопоставление префикса пространства имён с базовым каталогом

См. также

• /integrations/symfony/integration/ — сквозной справочник по связыванию.
• /integrations/symfony/install/ — установка и регистрация.
• /integrations/symfony/configuration/ — полное дерево конфигурации и таблица сервисов.
• /integrations/symfony/overview/ — сводка возможностей.