Справочник API для Laravel

Кратко

Пакет nextpdf/laravel связывает независимое от фреймворка ядро NextPDF с приложением Laravel. Вы работаете напрямую с четырьмя точками входа: фасадом Pdf для коротких сценариев создания документов, привязкой контейнера PdfDocumentInterface для создания документов через внедрение зависимостей, вспомогательным классом PdfResponse для HTTP-ответов на основе готовых документов и заданием очереди GeneratePdfJob для генерации за пределами запроса. Поставщик NextPdfServiceProvider регистрирует каждую привязку и обнаруживается автоматически, поэтому ручная настройка не требуется. Конфигурация в config/nextpdf.php управляет значениями по умолчанию, шрифтами, очередями, а также дополнительной подписью и службой меток времени (TSA).

Для быстрого старта: чтобы отправить PDF-файл прямо из контроллера, создайте документ и верните PdfResponse::download($document, 'file.pdf'). Это показано в первом примере ниже.

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

Приведённые ниже фрагменты охватывают три процесса, с которых обычно начинают работу. Каждый фрагмент проверен по исходному коду пакета; полные таблицы по каждому API-символу приведены далее.

Возврат PDF для скачивания из контроллера. Это самая распространённая задача:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(PdfDocumentInterface $document): Response
    {
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

Что делает этот код: внедряет новый документ, записывает одну строку и возвращает ответ attachment с Content-Type: application/pdf и заголовками безопасности Open Worldwide Application Security Project (OWASP). Используйте inline() вместо download(), чтобы открыть предпросмотр в браузере.

Создание и сохранение с помощью фасада Pdf. Это самый короткий путь для скриптов и простых сценариев:

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

Что делает этот код: фасад получает новый документ из контейнера, записывает одну ячейку и сохраняет готовый PDF на диск.

Генерация PDF вне потока запроса с помощью GeneratePdfJob:

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

Что делает этот код: ставит генерацию в очередь на воркере. Замыкание-конструктор получает документ из контейнера и возвращает его. Задание проверяет путь вывода .pdf перед сохранением. Имя очереди, тайм-аут и подключение берутся из config('nextpdf.queue.*').

Фасад

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

Символ	Параметры	Поведение по умолчанию	Возвращает	Исключения и сбои	Примечания
`NextPDF\Laravel\Facades\Pdf`	нет; статический акцессор фасада получает `NextPDF\Contracts\PdfDocumentInterface`	Laravel получает текущую привязку контейнера для интерфейса документа.	API для цепочки вызовов нижележащего документа ядра.	Сбой привязки контейнера Laravel, если поставщик не зарегистрирован.	Используйте его в коротких сценариях контроллера. Для сервисов и заданий предпочитайте внедрение через конструктор.
`Pdf::setTitle(string $title)`	`title`: заголовок документа.	Заменяет любой существующий заголовок.	`static`	Ошибки проверки ядра или ошибки во время записи.	Проксирует в ядро `Document`.
`Pdf::setAuthor(string $author)`	`author`: метаданные автора документа.	Заменяет предыдущего автора.	`static`	Ошибки проверки метаданных ядра.	Для метаданных уровня приложения предпочитайте настроенные значения по умолчанию.
`Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)`	`size`: необязательный размер страницы; `orientation`: по умолчанию `Portrait`.	Использует настроенный размер страницы или размер по умолчанию, если `size` опущен.	`static`	Ошибки проверки страницы ядра.	Указывайте явный `PageSize`, когда размер вывода важен.
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	Семейство шрифта, начертание и размер в пунктах.	Использует пустое начертание и размер 12 пт.	`static`	Ошибки реестра шрифтов или кодировки.	Предварительно загружайте рабочие шрифты через `nextpdf.preload_fonts`, когда важна задержка.
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	Размеры ячейки, текст, флаг рамки, флаг переноса строки и выравнивание.	Использует пустой текст, без рамки, без переноса строки и выравнивание по левому краю.	`static`	Ошибки макета или кодировки текста.	Используйте для простого вывода с фиксированным макетом.
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	Ширина ячейки, высота строки, текст, флаг рамки, выравнивание.	Без рамки и с выравниванием по левому краю.	`static`	Ошибки макета или кодировки текста.	Используйте, когда текст должен переноситься в пределах фиксированной ширины.
`Pdf::writeHtml(string $html)`	`html`: фрагмент HTML.	Отрисовывает на текущей странице и создаёт её при необходимости.	`static`	Ошибки отрисовки HTML в ядре.	Применяйте политики размера ввода и ресурсов перед приёмом недоверенного HTML.
`Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)`	Путь к файлу и необязательный прямоугольник размещения.	Позволяет документу ядра выбрать текущую позицию и естественный размер, когда координаты опущены.	`static`	Ошибки декодирования изображения, пути или макета.	Проверяйте политику источника изображения перед приёмом путей, заданных пользователем.
`Pdf::output(?string $filename = null, OutputDestination $dest = Inline)`	`filename`: необязательное имя; `dest`: назначение вывода.	Выводит inline, когда назначение опущено.	`string`	Ошибки сериализации ядра.	Для HTTP-ответов Laravel предпочитайте `PdfResponse`.
`Pdf::save(string $path)`	`path`: целевой путь в файловой системе.	Записывает готовый PDF на диск.	`void`	Ошибки файловой системы или ошибки записи ядра.	Проверяйте каталоги вывода в коде приложения.
`Pdf::getPdfData()`	нет.	Формирует байты PDF в памяти.	`string`	Ошибки сериализации ядра.	Используйте, когда телом ответа должен владеть другой объект фреймворка.

Поставщик сервисов и привязки

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

Символ	Параметры	Поведение по умолчанию	Возвращает	Исключения и сбои	Примечания
`NextPdfServiceProvider::register()`	нет.	Объединяет `config/nextpdf.php`; регистрирует реестры, фабрику документов, привязку документа, HTTP-клиент, клиент TSA, компонент подписи и необязательные контракты электронных счетов.	`void`	Ошибки разрешения контейнера или необязательного класса, если используется необязательная функция.	`FontRegistryInterface` и `ImageRegistry` используются совместно; документы всегда создаются заново.
`NextPdfServiceProvider::boot()`	нет.	Проверяет обязательные расширения PHP и публикует `nextpdf-config` в консольном режиме.	`void`	`RuntimeException`, если обязательное расширение недоступно.	Обязательные расширения — `mbstring` и `zlib`.
`NextPdfServiceProvider::provides()`	нет.	Возвращает идентификаторы отложенных сервисов.	`array<string>`	Не ожидается.	Включает `PdfDocumentInterface`, `DocumentFactoryInterface`, `FontRegistryInterface`, `SignerInterface`, `TsaClient`, `ClientInterface` и `nextpdf`.
`PdfDocumentInterface` / `nextpdf`	получается из контейнера Laravel.	Создаёт одноразовый `Document` через `DocumentFactoryInterface`, затем применяет настроенные значения по умолчанию и необязательные параметры PDF/A или Artisan.	`NextPDF\Core\Document`	Ошибки необязательного расширения, если оно настроено, но недоступно.	Получайте новый документ для каждого запроса или задания.
`DocumentFactoryInterface`	получается из контейнера Laravel.	Фабрика-синглтон, которая использует общие реестры шрифтов и изображений на время жизни процесса.	`DocumentFactoryInterface`	Ошибки настройки реестра.	Используйте для явного внедрения зависимостей.
`SignerInterface`	получается из контейнера Laravel.	Возвращает `null`, если `nextpdf.signature.enabled` не включён и пути к сертификатам не настроены.	`SignerInterface	null`	Ошибки загрузки сертификата или проверки уровня подписи.

Конфигурация

Используйте эту таблицу для поиска ключей nextpdf.*, которые относятся к среде выполнения и читаются привязками. Полный справочник по каждому ключу, включая переменные окружения и значения по умолчанию, доступен по адресу /integrations/laravel/configuration/.

Ключ	Тип	Поведение по умолчанию	Примечания
`nextpdf.fonts_path`	`string`	Если опущен, использует шрифты ресурсов Laravel.	Каталог для пользовательских шрифтов и прогрева.
`nextpdf.cache_path`	`string`	Путь к кешу приложения.	Убедитесь, что воркер PHP имеет право записи.
`nextpdf.preload_fonts`	`list<string>`	Пустой список.	Прогревает шрифты при создании реестра; после этого реестр блокируется.
`nextpdf.image_cache_mb`	`int`	Ограниченный размер кеша изображений.	Ограничивает память кеша изображений на время жизни процесса.
`nextpdf.defaults.*`	`array`	Создатель `NextPDF`, язык `en`, необязательные значения по умолчанию для автора и макета.	Применяется к каждому новому документу.
`nextpdf.artisan.*`	`array`	Рендерер Chrome отключён, если он не установлен и не настроен.	Сопоставляется с `ChromeRendererConfig::fromArray()`.
`nextpdf.signature.*`	`array`	Подпись по умолчанию отключена.	Сертификат, закрытый ключ, пароль, дополнительные сертификаты и уровень подписи.
`nextpdf.tsa.*`	`array`	TSA отключена, если URL пуст.	Поддерживает учётные данные, файлы для взаимной TLS-аутентификации (mTLS), тайм-аут, привязки открытых ключей и политику HTTP.
`nextpdf.ocsp_cache.*`	`array`	Кеш протокола OCSP включён с настроенным TTL.	Используется процессами проверки подписи, когда доступен.

HTTP-ответы

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

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

Задание очереди

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

Символ	Параметры	Поведение по умолчанию	Возвращает	Исключения и сбои	Примечания
`new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)`	`outputPath`: целевой `.pdf`; `builder`: получает `PdfDocumentInterface`; обратные вызовы необязательны.	Имя очереди, тайм-аут и подключение читаются из `config('nextpdf.queue.*')`.	Экземпляр задания.	Ошибки сериализации, если конструктор или обратные вызовы не удаётся сериализовать.	Конструктор должен вернуть настроенный документ.
`GeneratePdfJob::handle()`	нет.	Получает `PdfDocumentInterface`, применяет конструктор, проверяет путь вывода, затем сохраняет.	`void`	`InvalidArgumentException` для небезопасных путей вывода; ошибки записи ядра.	Отклоняет обёртки потоков, нулевые байты, сегменты `..` и пути без `.pdf`.
`GeneratePdfJob::failed(Throwable $exception)`	`exception`: причина сбоя.	Вызывает настроенный обратный вызов сбоя, если он задан.	`void`	Сбои обратного вызова.	Делайте обратные вызовы идемпотентными.
`GeneratePdfJob::then(callable $callback)`	`callback`: получает путь вывода.	Заменяет обратный вызов успеха.	`self`	Ошибки сериализации замыкания.	Помощник для цепочки вызовов при настройке диспетчеризации.
`GeneratePdfJob::catch(callable $callback)`	`callback`: получает выброшенный `Throwable`.	Заменяет обратный вызов сбоя.	`self`	Ошибки сериализации замыкания.	Используйте для оповещения или компенсирующей очистки.

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

PdfResponse всегда вызывает getPdfData() перед построением ответа. Это не ленивый построитель документов.
Данные задания в общих транспортах могут быть подменены; ограничивайте пути вывода каталогом, принадлежащим приложению.
Используйте новый документ для каждого запроса или задания. Не используйте один документ повторно между запросами.