安装 NextPDF Laravel 包

快速概览

使用 Composer 安装 nextpdf/laravel。自动发现（auto-discovery）会为你注册服务提供者。随后发布配置文件，以便按需编辑。该包会自动检测已安装的可选 NextPDF 扩展。

安装

composer require nextpdf/laravel

该包在其 composer.json 中声明了以下约束条件：

需求	约束条件
PHP	`>=8.4 <9.0`
`laravel/framework`	`^12.0`
`nextpdf/core`	`^3.0 \|\| ^5.2`
`psr/http-client`	`^1.0`

该包通过单一 PSR-4 映射表自动加载。NextPDF\Laravel\ 前缀会解析（resolve）到 src/Laravel/。这符合 PSR-4 中前缀对应基目录的规则（PSR-4 §3）。

概念总览

执行 composer require 之后，Laravel 包自动发现会读取该包的 extra.laravel 块（位于其 composer.json 中）。随后它会为你注册提供者与外观（facade）别名，因此无需手动编辑 config/app.php。以下就是该块：

{
  "extra": {
    "laravel": {
      "providers": [
        "NextPDF\\Laravel\\NextPdfServiceProvider"
      ],
      "aliases": {
        "Pdf": "NextPDF\\Laravel\\Facades\\Pdf"
      }
    }
  }
}

Laravel 的包文档说明了这一机制。extra.laravel.providers 数组会自动注册服务提供者，而 extra.laravel.aliases 数组会自动注册外观（facade）别名（Laravel 12 包开发指南， https://laravel.com/docs/12.x/packages 于 2026-05-18 获取）。

代码示例 — 快速上手

使用 nextpdf-config 标签发布配置文件。该标签名称定义在 NextPdfServiceProvider::boot() 中。

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

这会将 config/nextpdf.php 写入你的应用。提供者也会在 register() 期间把包默认配置合并到 nextpdf 键下，因此即使尚未发布配置文件，包也能运行。发布的作用只是让该文件在你的应用中可编辑。

确认提供者已被发现：

php artisan package:discover --ansi

代码示例 — 生产环境

为保证部署可重现，请锁定约束条件。只有在自行注册提供者时，才需要显式禁用发现：

{
  "extra": {
    "laravel": {
      "dont-discover": [
        "nextpdf/laravel"
      ]
    }
  }
}

禁用发现后，请在 bootstrap/providers.php 中自行注册提供者：

<?php

declare(strict_types=1);

return [
    App\Providers\AppServiceProvider::class,
    NextPDF\Laravel\NextPdfServiceProvider::class,
];

可选扩展

该包在 suggest 下列出可选配套包（位于其 composer.json 中）。运行时会检测这些包：

包	安装后的效果	检测点
`nextpdf/artisan`	存在 Chrome 工厂类时，会将 Chrome CDP HTML renderer（渲染器）配置应用到文档绑定	`NextPdfServiceProvider::register()` 会检查 Chrome 浏览器工厂类
`nextpdf/premium`	签名（PAdES B-B）、PDF/A 归档以及电子发票合约的具体实现会通过现有容器键解析	在首次容器解析时延迟解析

以相同方式安装扩展：

composer require nextpdf/artisan

无需再做任何接入配置。提供者会在下一次注册时检测到该扩展。

边界情况与陷阱

发布是幂等的。它不会覆盖既有的 config/nextpdf.php。如果你有意覆盖它，请加上 --force。
提供者是延迟加载的，因此运行一次可确认包存在的 php artisan package:discover 就足够了。绑定本身会在首次解析时才出现。
该包支持 nextpdf/core，在 ^3.0 与 ^5.2 两条主版本线上均受支持。请让 core 约束条件与你的应用所锁定的版本线保持一致。两者的 Laravel 适配层接口相同。
README 徽章与 composer.json 对 Apache-2.0 的标注一致。该包已从 LGPL-3.0-or-later 重新授权。迁移前已标记的版本仍维持原许可条款（见 CHANGELOG.md）。

性能

解析 nextpdf/core 是 composer require 成本的主要部分。提供者注册不会增加可测量的启动成本，因为所有绑定都是延迟加载的闭包。首次解析的构造成本记录在 /integrations/laravel/boot-and-discovery/。

安全注意事项

请从规范的 Packagist 包 nextpdf/laravel 安装。该包随附 SPDX REUSE 头部与一份 Apache-2.0 NOTICE 文件。请在 composer.json 中锁定约束条件，并提交 composer.lock，以确保已部署的 worker 解析到经过验证的依赖树。

符合性

主张	来源	条款	参考 ID
PSR-4 前缀映射到基目录	PSR-4 自动加载器	§3

Laravel 自动发现的键名已与官方 Laravel 12 包开发文档比对并佐证（https://laravel.com/docs/12.x/packages 于 2026-05-18 获取）。

商业背景

nextpdf/premium 增加了签名、PDF/A 与电子发票的具体实现。这是可选的 Enterprise 能力。本文记载的 Core 包无需任何代码变更即可采用它。见 https://nextpdf.dev/get-license/?intent=laravel-signing。

另请参阅

/integrations/laravel/overview/ — 包架构与绑定对照表
/integrations/laravel/quickstart/ — 首个可运行的控制器
/integrations/laravel/configuration/ — 逐一说明每个配置键
/integrations/laravel/boot-and-discovery/ — 发现内部机制与绑定生命周期