Интеграция NextPDF с Symfony

Кратко

Установите nextpdf/symfony, дайте Flex зарегистрировать пакет или сделайте это вручную, добавьте config/packages/nextpdf.yaml и внедрите PdfFactory. Эта страница служит ориентиром по подключению: каждый шаг ведёт к более подробному руководству.

Установка

composer require nextpdf/symfony

Пакету требуются nextpdf/core^3.0 || ^5.2, symfony/*^7.2 и psr/log^3.0. Классы автоматически загружаются под префиксом PHP Standards Recommendation (PSR)-4 NextPDF\Symfony\, сопоставленным с src/Symfony/. Автозагрузчик PSR-4 связывает этот префикс пространства имён с базовым каталогом (PSR-4 §2). Полный список требований и дополнительных пакетов см. в /integrations/symfony/install/.

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

Если вы используете Symfony Flex, запись extra.symfony.bundles в composer.json пакета регистрирует NextPDF\Symfony\NextPdfBundle во всех окружениях. Без Flex добавьте его в config/bundles.php самостоятельно:

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

Подробную последовательность загрузки и поведение прохода компилятора см. в /integrations/symfony/boot-and-discovery/.

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

Файл config/services.php пакета регистрирует следующие сервисы:

Сервис / псевдоним	Жизненный цикл
`NextPDF\Symfony\Service\PdfFactory`	общий, публичный; внедряйте именно его
`nextpdf.document` → `PdfDocumentInterface` → `Document`	необщий, публичный; создаётся заново при каждом получении
`NextPDF\Contracts\FontRegistryInterface`	общий, блокируется после прогрева
`NextPDF\Graphics\ImageRegistry`	общий, `kernel.reset`
`NextPDF\Contracts\DocumentFactoryInterface`	общий
`NextPDF\Symfony\Http\PdfResponse`	публичный вспомогательный класс без состояния

Привязка документа намеренно сделана необщей. PSR-11 разрешает контейнеру возвращать разные значения при последовательных вызовах get() для одного идентификатора. Новый документ исключает совместное состояние между запросами в долгоживущих процессах (PSR-11 §1.1.2). Полную таблицу сервисов и псевдонимов, включая условные привязки EInvoice, см. в /integrations/symfony/configuration/.

Публикация конфигурации

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

nextpdf: ~

Полное дерево конфигурации описано в /integrations/symfony/configuration/.

Первое использование

Внедрите PdfFactory, затем отдайте документ через PdfResponse:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class PdfController
{
    #[Route('/hello.pdf', name: 'hello_pdf')]
    public function hello(PdfFactory $pdf): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->cell(0, 10, 'Hello from NextPDF on Symfony.');

        return PdfResponse::inline($doc, 'hello.pdf');
    }
}

Полный контроллер и асинхронный сценарий через Messenger см. в /integrations/symfony/quickstart/.

Дымовой тест пакета

Проверьте подключение, не написав ни одной строки кода приложения:

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console lint:container

debug:container nextpdf должна вывести PdfFactory, псевдоним nextpdf.document и реестры. lint:container проверяет, что каждый аргумент сервиса можно разрешить. Чтобы проверить генерацию, добавьте показанный выше контроллер, затем запросите /hello.pdf.

Точки входа публичного API

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

Символ	Назначение
`NextPDF\Symfony\Service\PdfFactory::create()`	новый, предварительно настроенный `Document`
`NextPDF\Symfony\Http\PdfResponse::inline()` / `download()`	буферизованный ответ с заголовками безопасности
`NextPDF\Symfony\Http\PdfResponse::streamInline()` / `streamDownload()`	потоковый ответ с разбиением на фрагменты
`NextPDF\Symfony\Message\GeneratePdfMessage`	объект передачи данных (DTO) для асинхронной генерации (с валидацией)
`NextPDF\Symfony\Message\PdfBuilderInterface`	контракт построителя, разрешаемый обработчиком

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

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

Спецификация	Пункт	reference_id (идентификатор ссылки)	Утверждение
PSR-11	`psr_11_container#1.1.2.p4`		Контракт идентификаторов контейнера has()/get()
PSR-4	`psr_4_autoload#x1.x2.p5`		Сопоставление пространств имён автозагрузчиком

См. также

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