Быстрый старт NextPDF для Laravel

Кратко

В этом руководстве вы создадите из контроллера файл Portable Document Format (PDF), доступный для скачивания. Затем перенесёте ту же работу в задание очереди. Каждый фрагмент соответствует поведению, проверяемому набором тестов пакета.

Установка

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Концептуальный обзор

Три точки входа покрывают почти любой сценарий использования в Laravel. Фасад — самый быстрый способ начать. PdfResponse превращает документ в ответ по протоколу Hypertext Transfer Protocol (HTTP). Задание очереди выносит тяжёлую генерацию за пределы обработки запроса, поэтому её не нужно ждать. В руководстве поочерёдно рассматривается каждая точка входа. Производственные варианты добавляют обработку ошибок и описаны по адресу /integrations/laravel/production-usage/.

Пример кода — быстрый старт

1. Фасад

При каждом вызове фасад разрешает из контейнера новый документ. Контейнер — реестр сервисов Laravel. Этот фрагмент соответствует поведению, проверяемому tests/Unit/Laravel/Facades/PdfTest.php.

<?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'));

2. Ответ для скачивания из контроллера

PdfResponse::download() возвращает Illuminate\Http\Response с заголовком Content-Type: application/pdf, disposition attachment и заголовками безопасности Open Worldwide Application Security Project (OWASP). tests/Unit/Laravel/Http/PdfResponseTest.php проверяет код состояния, тип содержимого, префикс disposition и заголовки.

<?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(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

Чтобы показать предпросмотр прямо в браузере, замените download() на inline(). Для больших документов используйте streamInline() или streamDownload(). Они отправляют PDF детерминированными фрагментами по 64 КБ.

3. Генерация в очереди

GeneratePdfJob создаёт и сохраняет PDF в обработчике очереди. Замыкание-построитель получает документ, разрешённый из контейнера, и возвращает настроенный документ. tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php подтверждает, что задание создаёт файл именно по указанному пути вывода.

<?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. Перед записью задание проверяет путь в обработчике.

Пример кода — производственный

Производственные варианты добавляют явную обработку ошибок, обратные вызовы при успехе и сбое задания, а также типизированную стратегию исключений. Они подробно описаны по адресу /integrations/laravel/production-usage/.

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

Фасад возвращает отдельный экземпляр документа при каждом разрешении. Не кэшируйте Pdf::getFacadeRoot() для разных логических документов.
Если вы передаёте пустое имя файла в любую фабрику PdfResponse, по умолчанию используется document.pdf. Тесты ответа проверяют это значение по умолчанию.
Имена файлов с символами вне ASCII автоматически получают параметр RFC 5987 filename*=. Имена только в ASCII — нет.
GeneratePdfJob отклоняет обход каталогов, обёртки потоков, нулевые байты и любое расширение, отличное от .pdf. Задание выбрасывает InvalidArgumentException в обработчике.

Производительность

Генерация одностраничного документа укладывается в бюджет времени на страницу, указанный во вводных метаданных, с большим запасом. Перенос генерации в GeneratePdfJob полностью выводит время сборки PDF за пределы HTTP-запроса. Ответ возвращается, как только задание отправлено в очередь.

Замечания по безопасности

PdfResponse предоставляет фабрики, применяющие фиксированный набор заголовков OWASP. Они также очищают имя скачиваемого файла. Задание очереди проверяет заданный путь вывода. Подробное описание угроз доступно по адресу /integrations/laravel/security-and-operations/.

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

Это руководство не привязано к какому-либо нормативному стандарту. Каждый фрагмент сверен с исходным кодом пакета и соответствующим тестом в каталоге tests/.

Коммерческий контекст

Вывод с подписью и вывод PDF/A доступны в nextpdf/premium как опциональная возможность Enterprise. Для описанного здесь пакета Core не нужны изменения кода, чтобы её задействовать. См. https://nextpdf.dev/get-license/?intent=laravel-signing.

См. также

/integrations/laravel/install/ — установка и публикация конфигурации
/integrations/laravel/production-usage/ — контроллер и задание с внедрением зависимостей и обработкой ошибок
/integrations/laravel/configuration/ — используемые здесь ключи конфигурации
/integrations/laravel/overview/ — архитектура и жизненный цикл привязок