Справочник по Symfony API

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

Пакет Symfony предоставляет регистрацию бандла, дерево конфигурации, внедряемую фабрику для создания новых документов, помощники для HTTP-ответов и типы Messenger для асинхронной генерации. Большая часть кода приложения использует только два символа: сервис PdfFactory, который вы внедряете для создания Document, и помощник PdfResponse, который превращает этот документ в защищённый HTTP-ответ. Остальные символы (бандл, расширение, проход компилятора, дерево конфигурации, Messenger DTO и обработчик) — это связующий слой, который вы настраиваете один раз или которым за вас управляет фреймворк.

С чего начать: внедрите NextPDF\Symfony\Service\PdfFactory, вызовите create(), чтобы получить новый Document, и верните его с помощью NextPDF\Symfony\Http\PdfResponse::download(). Первый пример показывает этот процесс.

Типовые задачи

Используйте эти три готовых к запуску фрагмента кода для самых типовых задач. Каждый фрагмент использует только проверенные символы, описанные в таблицах ниже.

Вернуть PDF-файл для загрузки из контроллера: внедрите фабрику, создайте документ и передайте его помощнику ответов:

<?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 InvoiceController
{
    #[Route('/invoice/{number}', name: 'invoice_pdf')]
    public function download(PdfFactory $pdf, string $number): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, "Invoice #{$number}");

        return PdfResponse::download($doc, "invoice-{$number}.pdf");
    }
}

Что это делает: PdfFactory::create() возвращает новый, предварительно настроенный Document. PdfResponse::download() отправляет его с Content-Type: application/pdf, как вложение и с фиксированными заголовками безопасности бандла.

Потоковая передача большого PDF, чтобы снизить пиковое потребление памяти: используйте помощник потоковой передачи и верните StreamedResponse:

<?php

declare(strict_types=1);

namespace App\Controller;

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

final class ReportController
{
    #[Route('/report', name: 'report_pdf')]
    public function report(PdfFactory $pdf): StreamedResponse
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, 'Annual report');

        return PdfResponse::streamDownload($doc, 'annual-report.pdf');
    }
}

Что это делает: PdfResponse::streamDownload() выдаёт материализованный PDF по частям и не указывает Content-Length; для встроенного эквивалента используйте streamInline().

Запустить асинхронную генерацию PDF: отправьте GeneratePdfMessage в транспорт Messenger, чтобы отрисовка выполнялась на воркере:

<?php

declare(strict_types=1);

namespace App\Controller;

use App\Pdf\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Routing\Attribute\Route;

final class QueueController
{
    #[Route('/invoice/{id}/queue', name: 'invoice_queue')]
    public function queue(MessageBusInterface $bus, int $id): Response
    {
        $bus->dispatch(new GeneratePdfMessage(
            builderClass: InvoicePdfBuilder::class,
            outputPath: '/var/storage/invoices/' . $id . '.pdf',
            builderContext: ['invoice_id' => $id],
        ));

        return new Response('PDF generation queued.', 202);
    }
}

Что это делает: DTO содержит строку класса построителя и проверенный путь вывода. Обработчик разрешает построитель, создаёт документ и сохраняет его на воркере. Класс построителя реализует PdfBuilderInterface и регистрируется в локаторе сервисов (настройку локатора и воркера см. в кратком руководстве по Symfony).

Фабрика

Используйте эту таблицу для точного описания конструктора и контракта create() для внедряемого сервиса, который создаёт новые документы.

Символ	Параметры	Поведение по умолчанию	Возвращает	Выбрасывает или завершается с ошибкой	Примечания
`new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)`	`factory`: основная фабрика; `defaults`: создатель, автор, язык, поля; `pdfa`: необязательный профиль PDF/A; `artisanConfig`: необязательная конфигурация рендерера Chrome.	Значения по умолчанию применяются только при наличии конфигурации.	`PdfFactory`	Ошибки конфигурации контейнера.	Сервис может быть синглтоном, поскольку `create()` возвращает новый документ.
`PdfFactory::create()`	нет.	Применяет создателя и язык; применяет автора только при непустом значении; применяет PDF/A и конфигурацию Artisan только при их наличии.	`NextPDF\Core\Document`	Ошибки конфигурации ядра.	Используйте один раз на запрос, команду или сообщение.
`PdfFactory::setArtisanAvailable(bool $available)`	`available`: флаг доступности на этапе компиляции.	Отключено, пока проход компилятора не включит этот флаг.	`void`	не ожидается.	Внутренний хук, который вызывает проход компилятора необязательного расширения.
`PdfFactory::setProAvailable(bool $available)`	`available`: флаг доступности на этапе компиляции.	Отключено, пока проход компилятора не включит этот флаг.	`void`	не ожидается.	Внутренний хук для доступности Premium.

Бандл, расширение и конфигурация

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

Символ	Параметры	Поведение по умолчанию	Возвращает	Выбрасывает или завершается с ошибкой	Примечания
`NextPdfBundle::build(ContainerBuilder $container)`	Построитель контейнера Symfony.	Вызывает родительский метод build и регистрирует `OptionalExtensionPass`.	`void`	Ошибки регистрации прохода компилятора.	Включает обнаружение необязательных возможностей Artisan и Premium.
`NextPdfBundle::getPath()`	нет.	Возвращает корневой путь пакета.	`string`	не ожидается.	Используется механизмом обнаружения бандлов Symfony и загрузкой ресурсов.
`NextPdfExtension::load(array $configs, ContainerBuilder $container)`	Массивы пользовательской конфигурации и построитель контейнера.	Обрабатывает конфигурацию `nextpdf`, сохраняет разрешённые параметры, загружает определения сервисов и проверяет обязательные расширения.	`void`	Ошибки проверки конфигурации, загрузки сервисов или отсутствующего расширения.	Обязательные расширения — `mbstring` и `zlib`.
`NextPdfExtension::getAlias()`	нет.	Использует `nextpdf` в качестве корневого ключа конфигурации.	`string`	не ожидается.	Настройте бандл под `nextpdf:`.
`Configuration::getConfigTreeBuilder()`	нет.	Определяет проверенное дерево конфигурации `nextpdf`.	`TreeBuilder`	Ошибки определения конфигурации Symfony.	По возможности повторяет форму конфигурации Laravel.
`OptionalExtensionPass::process(ContainerBuilder $container)`	Построитель контейнера Symfony.	Обнаруживает необязательные сервисы Artisan и Premium и устанавливает флаги доступности фабрики.	`void`	Ошибки настройки прохода компилятора.	Выполняется во время компиляции контейнера.

Ключ конфигурации	Тип	Поведение по умолчанию	Примечания
`page_format`	enum	`A4`; допустимые значения включают `A3`, `A5`, `Letter`, `Legal` и `Tabloid`.	Применяется при создании документа по умолчанию.
`orientation`	enum	`P`; допустимые значения — `P` и `L`.	Используйте явные вызовы документа, когда странице нужна другая ориентация.
`unit`	enum	`mm`; допустимые значения — `pt`, `mm`, `cm` и `in`.	Согласует значения по умолчанию фреймворка с единицами ядра.
`pdfa`	`string	null`	`null`; допустимые значения — `4`, `4e` и `4f`.
`fonts_path` / `cache_path`	`string`	Путь к шрифтам проекта и путь к кешу ядра.	Сохраняйте каждый путь доступным для чтения или записи в соответствии с его ролью во время выполнения.
`signature.*`	`array`	Отключено по умолчанию с уровнем подписи `B-B`.	Предоставляет сертификат, ключ, пароль, дополнительные сертификаты и уровень.
`tsa.*`	`array`	Отключено, когда URL равен `null`; тайм-аут по умолчанию составляет 30 секунд.	Поддерживает учётные данные, файлы взаимной TLS-аутентификации (mTLS), закрепление открытых ключей и политику HTTP.
`ocsp_cache.*`	`array`	Включено со временем жизни (TTL) 86400 секунд.	Используется при проверке и в процессах долгосрочных подписей, когда это доступно.
`messenger.*`	`array`	Транспорт `async`, тайм-аут 120, 3 повтора.	Используется процессами асинхронной генерации.
`artisan.*`	`array`	Рендерер Chrome отключён, пока он не настроен и не установлен.	Сопоставляется с `ChromeRendererConfig`, когда необязательный рендерер доступен.
`defaults.*`	`array`	Создатель `NextPDF`, автор пустой, язык `en`, поля и шрифт по умолчанию.	Применяется через `PdfFactory::create()`.

Ответы HTTP

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

Символ	Параметры	Поведение по умолчанию	Возвращает	Выбрасывает или завершается с ошибкой	Примечания
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: готовый документ; `filename`: имя файла ответа.	Добавляет `.pdf`, если оно отсутствует.	`Symfony\Component\HttpFoundation\Response`	Ошибки сериализации ядра.	Устанавливает тип содержимого PDF и защитные заголовки.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Так же, как `inline`; режим — вложение.	Ответ, который браузер скачивает.	`Response`	Так же, как `inline`.	Используйте для явных загрузок.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Так же, как `inline`.	Выдаёт байты материализованного PDF по частям.	`StreamedResponse`	Так же, как `inline`.	Не избавляет от материализации документа.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Так же, как `streamInline`; режим — вложение.	Ответ потоковой загрузки.	`StreamedResponse`	Так же, как `streamInline`.	Примените политику размера вывода перед отрисовкой.

Messenger (асинхронная генерация)

Используйте эту таблицу для асинхронного сценария: DTO сообщения, которое вы отправляете, интерфейс построителя, который вы реализуете, и обработчик, который выполняется на воркере.

Символ	Параметры	Поведение по умолчанию	Возвращает	Выбрасывает или завершается с ошибкой	Примечания
`new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])`	`builderClass`: строка класса, реализующая `PdfBuilderInterface`; `outputPath`: целевой файл `.pdf`; `builderContext`: сериализуемые данные.	Пустой массив контекста.	DTO сообщения.	`InvalidArgumentException` при недопустимом полностью квалифицированном имени класса (FQCN), обёртке потока, нулевом байте, обходе каталогов, пустом пути или цели, не являющейся `.pdf`.	Транспорты Messenger передают данные, а не замыкания.
`PdfBuilderInterface::build(Document $document, array $context): Document`	`document`: новый настроенный документ; `context`: сериализуемые данные сообщения.	Контекста по умолчанию нет, кроме значения сообщения.	Настроенный `Document`.	Исключения, специфичные для построителя.	Делайте построители детерминированными и идемпотентными.
`new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)`	Фабрика PDF и помеченный локатор сервисов построителей.	Во время конструирования документ не создаётся.	`GeneratePdfHandler`	Ошибки конфигурации контейнера.	Локатор должен предоставлять только реализации `PdfBuilderInterface`.
`GeneratePdfHandler::__invoke(GeneratePdfMessage $message)`	`message`: проверенный DTO сообщения.	Разрешает построитель из контейнера, создаёт документ и сохраняет его.	`void`	Отсутствующий сервис построителя, недопустимый результат построителя, ошибки записи ядра.	Предпочитайте построители-сервисы статическим обратным вызовам.

Заметки для разработчиков

Не храните Document как сервис. Храните PdfFactory и вызывайте create() для каждой рабочей операции.
В очередь помещайте только сериализуемый контекст. Не помещайте открытые потоки, замыкания или объекты запроса в builderContext.
Используйте политику пути вывода строже, чем DTO, если в развёртывании у арендаторов отдельные корни хранилища.