Laravel API 参考

速览

这个 nextpdf/laravel 包会把与 Framework（框架）无关的 NextPDF 核心接入 Laravel 应用。它提供四个你会直接调用的组件：用于快速编写的 Pdf facade、用于通过注入方式创建文档的 PdfDocumentInterface 容器绑定、把完成的文档转换为 HTTP 响应的 PdfResponse 辅助函数，以及用于在请求之外生成 PDF 的 GeneratePdfJob 队列任务。NextPdfServiceProvider 会注册每一项绑定，并支持自动发现，因此无需手动配置。config/nextpdf.php 中的配置会决定默认值、字体、队列，以及可选的签名与 TSA 功能。

可以从这里开始：如果要直接从控制器返回 PDF，先创建一份文档，再返回 PdfResponse::download($document, 'file.pdf')，请参考下方第一个示例。

常见任务

下方的代码片段涵盖你最先会用到的三种流程。每一个都已对照包的源码验证过；完整的逐符号表格接在后面。

从控制器返回可下载的 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 与 OWASP 安全响应头。把 download() 换成 inline()，即可改为在浏览器中预览。

用 Pdf facade 编写并保存，这是脚本与简短流程的最短路径：

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

它的作用：facade 会从容器 resolve（解析）出一份全新文档、写入一个 cell，再把完成的 PDF 保存到磁盘。

用 GeneratePdfJob 在请求线程之外生成 PDF：

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

它的作用：把生成工作加入 worker 队列。builder（构建器）闭包会收到一份由容器解析出的文档并返回它。任务会在保存前验证 .pdf 输出路径。队列名称、超时与连接都来自 config('nextpdf.queue.*')。

Facade（外观模式）

这个 Pdf facade 会以静态方式委派一份全新的核心 Document；适合用于静态写法读起来更顺畅的简短控制器流程。每一列都是一个被委派的文档方法。

符号	参数	默认行为	回传	抛出或失败的情况	备注
`NextPDF\Laravel\Facades\Pdf`	无；静态 facade 访问器会解析出 `NextPDF\Contracts\PdfDocumentInterface`	Laravel 会为文档接口解析出当前的容器绑定。	底层核心文档的流畅式 API。	如果未注册 provider，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` 时，会使用 configured/default 页面尺寸。	`static`	核心页面验证错误。	当输出尺寸很重要时，请明确指定 `PageSize`。
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	字体族、样式与点数大小。	空白样式与 12 pt 大小。	`static`	字体注册或编码错误。	当延迟很重要时，请通过 `nextpdf.preload_fonts` 预先加载生产环境字体。
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	cell 区块、文字、边框标志、换行标志、对齐方式。	空白文字、无边框、不换行、左对齐。	`static`	布局或文字编码错误。	用于简单的固定布局输出。
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	cell 宽度、行高、文字、边框标志、对齐方式。	无边框且左对齐。	`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`	核心序列化错误。	在 Laravel HTTP 响应中，建议优先使用 `PdfResponse`。
`Pdf::save(string $path)`	`path`：文件系统目标。	把完成的 PDF 写入磁盘。	`void`	文件系统或核心写入错误。	在应用代码中验证输出目录。
`Pdf::getPdfData()`	无。	在内存中生成 PDF 数据。	`string`	核心序列化错误。	当响应主体必须由另一个框架对象承载时使用。

Service provider 与绑定

当你需要直接解析或覆盖某个容器条目时，请查阅这张表，例如把 DocumentFactoryInterface 注入某个服务，或查看 provides() 延迟加载了哪些条目。

符号	参数	默认行为	回传	抛出或失败的情况	备注
`NextPdfServiceProvider::register()`	无。	会合并 `config/nextpdf.php`，并注册各注册表、文档工厂、文档绑定、HTTP 客户端、TSA 客户端、签名器，以及可选的电子发票合约。	`void`	使用某项功能时，可能出现容器或可选类解析错误。	`FontRegistryInterface` 与 `ImageRegistry` 为共享实例；文档则永远是全新的。
`NextPdfServiceProvider::boot()`	无。	会验证必要的 PHP 扩展，并在 console 模式下发布 `nextpdf-config`。	`void`	`RuntimeException`：当必要的扩展无法使用时抛出。	必要的扩展为 `mbstring` 与 `zlib`。
`NextPdfServiceProvider::provides()`	无。	返回延迟加载的服务 ID。	`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 worker 可写入。
`nextpdf.preload_fonts`	`list<string>`	空列表。	会在创建注册表时预热，之后注册表即被锁定。
`nextpdf.image_cache_mb`	`int`	有上限的图像缓存大小。	限制进程生命周期内的图像缓存内存。
`nextpdf.defaults.*`	`array`	创建者 `NextPDF`、语言 `en`，以及可选的作者与布局默认值。	应用到每一份全新文档。
`nextpdf.artisan.*`	`array`	除非已安装并配置，否则 Chrome renderer（渲染器）为停用。	映射到 `ChromeRendererConfig::fromArray()`。
`nextpdf.signature.*`	`array`	签名默认为停用。	凭证、私钥、密码、额外凭证，以及签名级别。
`nextpdf.tsa.*`	`array`	当 URL 为空时，TSA 为停用。	支持凭证、mTLS 文件、超时、公钥固定，以及 HTTP 策略。
`nextpdf.ocsp_cache.*`	`array`	OCSP 缓存启用，并使用已配置的 TTL。	在可用时，供签名验证流程使用。

HTTP 响应

当你要通过 HTTP 返回一份完成的文档，并需要在 inline 显示、attachment 下载或流式输出之间做选择时，请使用这张表。

符号	参数	默认行为	回传	抛出或失败的情况	备注
`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 KB 块发出。	`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.*')` 读取。	任务实例。	如果 builder 或回调无法序列化，则发生序列化错误。	builder 必须返回配置好的文档。
`GeneratePdfJob::handle()`	无。	会解析出 `PdfDocumentInterface`、应用 builder、验证输出路径，接着保存。	`void`	`InvalidArgumentException`：对不安全的输出路径抛出；以及核心写入错误。	会拒绝流包装器、null 字节、`..` 区段，以及非 `.pdf` 的路径。
`GeneratePdfJob::failed(Throwable $exception)`	`exception`：失败原因。	存在已配置的失败回调时，会调用它。	`void`	回调失败。	让回调保持幂等。
`GeneratePdfJob::then(callable $callback)`	`callback`：会收到输出路径。	会替换成功回调。	`self`	可序列化闭包的错误。	用于派发配置的流畅式辅助方法。
`GeneratePdfJob::catch(callable $callback)`	`callback`：会收到抛出的 `Throwable`。	会替换失败回调。	`self`	可序列化闭包的错误。	用于警报或补偿性清理。

开发备注

PdfResponse 一律会在构建响应前调用 getPdfData()。它并非延迟式的文档构建器。
在共享传输中，队列载荷可能被篡改；请把输出路径限制在应用自有的目录内。
每个请求或任务都使用一份全新文档。不要跨请求重复使用同一份文档。