NextPDF Laravel 集成

概览

本指南说明如何将 NextPDF 接入 Laravel 12 应用。你会依次完成六个阶段：安装软件包、让 Laravel 自动发现它、解析（resolve）容器绑定、返回一个 HTTP 响应，以及执行一个队列任务。每个阶段都附有对应领域的深入参考文档链接。

安装

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

启动与自动发现

Laravel 会从软件包的 composer.jsonextra.laravel 配置段自动发现 service provider（服务提供者）和 facade 别名。你不需要编辑 config/app.php。autoload 映射只包含一条 PSR-4 条目。按照 PSR-4 前缀对应基目录的规则（PSR-4 §3），NextPDF\Laravel\ 前缀会解析到 src/Laravel/。该 provider 会延迟加载。只有当其中某个 provides() 条目首次被解析时，它才会启动。完整的自动发现内部机制请见 /integrations/laravel/boot-and-discovery/.

容器绑定

从容器中解析文档契约。已绑定的标识符会解析为其注册的条目（PSR-11 §1.1.2）。文档绑定使用工厂（factory），因此每次解析都会得到一份全新的文档。字体和图像注册表是单例（singleton），因此每次解析都会返回同一个共享实例。完整的绑定生命周期表见 /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/.

Service provider 与软件包冒烟测试

该软件包附带一套基于 Testbench 的测试，用于端到端验证 provider。下面是一个可以加入使用方应用的最小冒烟测试：

<?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`	指向全新文档的静态 proxy	/integrations/laravel/quickstart/（快速上手）
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	由容器解析出的文档	/integrations/laravel/production-usage/（生产环境用法）
`NextPDF\Laravel\Http\PdfResponse`	内嵌/下载/流式 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。这些契约已经绑定，但缺少它时会在首次解析时出错。

性能

由于 provider 是延迟加载的，端到端接线不会增加启动成本。首次解析的构建成本和字体预热成本，详见 /integrations/laravel/boot-and-discovery/ 一节。

安全性注意事项

PdfResponse 会应用一组固定的 OWASP 标头。GeneratePdfJob 会在 worker 上验证它的输出路径。威胁模型见 /integrations/laravel/security-and-operations/ 一节。

一致性

声明	来源	条款	参考 ID
已绑定的标识符会解析为其注册的条目	PSR-11 容器	§1.1.2
PSR-4 前缀对应基目录	PSR-4 自动加载器	§3

商业情境

安装 nextpdf/premium 后，签名、PDF/A 和电子发票契约都会通过同一个 provider 集成。这是一项可选的 Enterprise 能力。此处记录的 Core 软件包无需任何代码变更即可采用该能力。请见 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/ — 自动发现与生命周期