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

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

Это руководство помогает настроить NextPDF в приложении Laravel 12. Вы проходите шесть этапов: устанавливаете пакет, позволяете Laravel автоматически обнаружить его, публикуете конфигурацию, разрешаете привязки контейнера, возвращаете HTTP-ответ и запускаете задание в очереди. Для каждого этапа есть ссылка на подробный справочник по соответствующей теме.

Установка

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

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

Laravel автоматически обнаруживает поставщик служб и псевдоним фасада из блока composer.jsonextra.laravel пакета. Редактировать config/app.php не нужно. Карта автозагрузки использует одну запись PSR-4. Префикс NextPDF\Laravel\ разрешается в src/Laravel/ по правилу сопоставления префикса с базовым каталогом PSR-4 (PSR-4 §3). Поскольку поставщик отложенный, он загружается только при первом разрешении одной из записей из provides(). Подробное описание механизма обнаружения см. в /integrations/laravel/boot-and-discovery/.

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

Разрешите контракт документа из контейнера. Привязанный идентификатор разрешается в зарегистрированную для него запись (PSR-11 §1.1.2). Привязка документа работает как фабрика, поэтому каждое разрешение возвращает новый документ. Реестры шрифтов и изображений являются одиночками, поэтому каждое разрешение возвращает один и тот же общий экземпляр. Полную таблицу времени жизни привязок см. в /integrations/laravel/overview/ и /integrations/laravel/boot-and-discovery/.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Wired through the container', newLine: true);

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

php artisan vendor:publish --tag=nextpdf-config

Эта команда записывает config/nextpdf.php. Справочник по конфигурации описывает каждый ключ, соответствующую переменную окружения и значение по умолчанию в /integrations/laravel/configuration/.

Дымовой тест поставщика служб и пакета

Пакет включает набор тестов на основе Testbench, который полностью проверяет поставщик. Добавьте этот минимальный дымовой тест в приложение, которое использует пакет:

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

Эти два утверждения повторяют одноразовые проверки соответствия пакета в EInvoiceServiceProviderIntegrationTest. Они подтверждают, что документ привязан как фабрика, а реестр шрифтов является заблокированным одиночкой.

Публичные точки входа API

Точка входа	Назначение	Справочник
`NextPDF\Laravel\Facades\Pdf`	Статический прокси для нового документа	Быстрый старт — /integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	Документ, разрешённый через контейнер	Использование в продакшене — /integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	Inline-ответы, ответы для скачивания и потоковые HTTP-ответы	Безопасность и эксплуатация — /integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	Генерация в очереди	Использование в продакшене — /integrations/laravel/production-usage/

Пример кода — продакшен

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

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

Разрешайте PdfDocumentInterface, а не конкретный Document, чтобы привязка оставалась тестируемой и заменяемой.
SignerInterface и TsaClient разрешаются в null, пока они не настроены. Всегда проверяйте значение на null.
Контракты электронных счетов требуют nextpdf/premium. Они привязаны, но при первом разрешении без него вызывают ошибку.

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

Сквозная интеграция не увеличивает затраты на загрузку, поскольку поставщик отложенный. Затраты на создание при первом разрешении и прогрев шрифтов описаны в /integrations/laravel/boot-and-discovery/.

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

PdfResponse применяет фиксированный набор заголовков Open Worldwide Application Security Project (OWASP). GeneratePdfJob проверяет путь вывода на воркере. Модель угроз см. в /integrations/laravel/security-and-operations/.

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

Утверждение	Источник	Пункт	reference_id (идентификатор ссылки)
Привязанный идентификатор разрешается в зарегистрированную для него запись	PSR-11 Container (контейнер)	§1.1.2
Префикс PSR-4 сопоставляется с базовым каталогом	PSR-4 Autoloader (автозагрузчик)	§3

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

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

См. также

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