Установка бандла NextPDF для Symfony

Кратко

Установите бандл через Composer. Если приложение использует Symfony Flex, бандл зарегистрируется автоматически. Без Flex зарегистрируйте его один раз в config/bundles.php.

Требования

Эти ограничения указаны в composer.json бандла.

Зависимость	Ограничение
php	>=8.4 <9.0
nextpdf/core	^3.0 || ^5.2
symfony/framework-bundle	^7.2
symfony/dependency-injection	^7.2
symfony/config	^7.2
symfony/http-foundation	^7.2
psr/log	^3.0

Во время сборки контейнера бандл также проверяет наличие двух расширений PHP: ext-mbstring и ext-zlib. Любая поддерживаемая среда выполнения PHP включает оба расширения. Если хотя бы одно отсутствует, защитная проверка сразу прерывает работу с понятным сообщением.

Дополнительные пакеты

В composer.json бандла эти пакеты объявлены в секции suggest. Добавляйте их, когда нужна функциональность, которую они предоставляют:

Пакет	Добавляет
nextpdf/artisan	Отрисовка HTML через Chrome CDP; автоматически определяется на этапе компиляции
nextpdf/premium	Архивирование PDF/A и цифровая подпись (устанавливает уровень Pro); автоматически определяется на этапе компиляции
symfony/messenger	Асинхронная генерация PDF через обработчик Messenger

Установка с помощью Composer

composer require nextpdf/symfony

Бандл автоматически загружается по префиксу PHP Standard Recommendation 4 (PSR-4) NextPDF\Symfony\, сопоставленному с src/Symfony/. Это сопоставление объявлено в composer.jsonautoload.psr-4. Автозагрузчик, сгенерированный Composer, сопоставляет префикс пространства имён с этим базовым каталогом, как определено в PSR-4 §2.

Регистрация бандла

Symfony Flex (рекомендуется)

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

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

В приложении с включённым Flex эта запись добавляет бандл в config/bundles.php для всех окружений (all). Редактировать файл вручную не нужно. Описание модели регистрации см. в официальной документации Symfony по бандлам (https://symfony.com/doc/current/bundles.html).

Ручная регистрация (без Flex)

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

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

Класс бандла — NextPDF\Symfony\NextPdfBundle. Он расширяет базовый класс Symfony Symfony\Component\HttpKernel\Bundle\Bundle. Метод getPath() бандла возвращает корневой каталог пакета. Метод build() регистрирует проход компилятора OptionalExtensionPass.

Создание файла конфигурации

Псевдоним конфигурации бандла — nextpdf. Создайте config/packages/nextpdf.yaml. После публикации рецепт Flex сам добавит сюда копию со значениями по умолчанию. Минимальный файл, использующий только встроенные значения по умолчанию, выглядит так:

nextpdf: ~

У каждого ключа есть значение по умолчанию, поэтому пустая конфигурация допустима. Полное дерево конфигурации описано на странице /integrations/symfony/configuration/.

Проверка установки

Убедитесь, что контейнер видит сервисы бандла:

php bin/console debug:container nextpdf

В списке должны присутствовать сервисы, включая псевдоним nextpdf.document и NextPDF\Symfony\Service\PdfFactory. Чтобы посмотреть итоговую конфигурацию, выполните:

php bin/console debug:config nextpdf

Эта команда выводит объединённое дерево конфигурации: ваши переопределения и значения по умолчанию.

Пограничные случаи и подводные камни

• Диапазон ограничений core — бандл принимает nextpdf/core^3.0 || ^5.2. Composer выбирает версию, которая удовлетворяет остальному графу зависимостей. Закрепите одну мажорную версию в composer.json приложения, если вам нужна детерминированная версия движка.
• Защита при отсутствии расширения — если php bin/console при запуске завершается с ошибкой и сообщает о ext-mbstring или ext-zlib, включите указанное расширение в php.ini. Немедленное прерывание работы является намеренным поведением, а не дефектом бандла.
• Flex не зарегистрировал бандл — очистите кэш Composer и переустановите пакет. Если вы не используете Flex, выполните шаг ручной регистрации в config/bundles.php.

Соответствие стандартам

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

Спецификация	Раздел	Идентификатор ссылки (reference_id)	Утверждение
PSR-4	psr_4_autoload#x1.x2.p5		Сопоставление префикса пространства имён с каталогом в автозагрузчике

См. также

• /integrations/symfony/overview/ — что предоставляет бандл.
• /integrations/symfony/configuration/ — полное дерево конфигурации и таблица сервисов.
• /integrations/symfony/quickstart/ — первый работающий контроллер.
• /integrations/symfony/boot-and-discovery/ — подробно о процессе обнаружения и последовательности загрузки.