NextPDF Gotenberg 集成

概览

本页说明如何将桥接器接入应用的其他部分。先安装软件包并完成连接，再把转换后的 PDF 接入 NextPDF 后处理管线。桥接器负责将 Office 文件转换为 PDF，后续处理则交由管线完成。本页是 /integrations/gotenberg/boot-and-discovery/ 的任务导向配套文档，后者说明连接为何采用这种设计。

安装

composer require nextpdf/gotenberg

这会同时引入 nextpdf/core ^3.0 与 PSR HTTP 合约。请另行安装 PSR-18 客户端和 PSR-17 工厂，作为独立软件包使用。桥接器只依赖这些接口，具体库由你自行选择。完整安装步骤，包括如何通过 HTTPS 部署 Gotenberg 服务，请参阅 /integrations/gotenberg/install/。

连接

使用一个配置对象和 PSR 协作对象构造桥接器。同时注入响应工厂，以启用 DNS 固定、TLS 固定的传输层：

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    apiKey: $apiKey,
);

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

桥接器要求配置的 URL 必须使用 HTTPS。它会在发送任何请求前拒绝纯 http://。请在 TLS 终止点之后运行 Gotenberg，并让桥接器指向该 HTTPS 端点。

容器绑定

在宿主容器中注册三类对象。第一类是根据你的配置来源构造的 GotenbergConfig。第二类是你的 PSR-18 客户端以及 PSR-17 工厂。第三类是 GotenbergBridge，由前两类连接而成。本软件包本身不提供任何绑定。框架原生注册由专用的框架集成包提供。请参阅 /integrations/gotenberg/boot-and-discovery/。

配置

服务描述符及其各项限制都位于 GotenbergConfig 的字段中。这些字段涵盖 API URL、超时时间、大小上限、bearer token，以及 TLS 固定。每次请求的选项 landscape 与 nativePageRanges，则改由负载类型字段表示。/integrations/gotenberg/configuration/ 记录了每个字段，包括其类型、默认值与作用。

将转换后的 PDF 接入 NextPDF 管线

典型端到端流程如下：

使用 convertFile() 或 convertString() 转换 Office 文件。
取出 $result->pdfData，其中存放原始 PDF 字节，并将其载入一份 NextPDF 文档。
应用后处理，例如页面组装、水印、PDF/A 转换或数字签名。

步骤 3 属于 NextPDF 的职责，而非桥接器的职责。nextpdf/premium 软件包提供签名、PDF/A 配置文件与水印。请将转换与后处理保持为相互独立的阶段。这样，你就能分别诊断每一项失败。

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

Pro 版的 PAdES 支持仅限 B-B 基准级别。它不提供 B-T、B-LT 或 B-LTA。通过此桥接器转换文件，并不意味着具备任何时间戳或长期验证能力。

冒烟测试

完成连接后，确认此集成可以运行。你不需要转换真实文件就能做到这一点：

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

isAvailable() 会先验证 URL，这一步不会产生任何网络流量。随后它会向 <apiUrl>/health 发送一个 HEAD。之后，再转换一份已知正常的小型文件。这会走完整个通往 <apiUrl>/forms/libreoffice/convert 的 multipart 路径，并完成响应验证。

公开 API 入口

此集成使用的公开接口：

GotenbergConfig — 不可变的服务描述符与各项限制；fromArray() 会根据配置数组构造它。
GotenbergBridge::convertFile(string $path) — 转换磁盘上的文件。
GotenbergBridge::convertString(string $bytes, string $fileName) — 转换存放在内存中的字节。
GotenbergBridge::isAvailable() — 不会抛出异常的就绪性探测。
GotenbergConvertResult — 包含 pdfData、sourceFormat、isValid() 与 size()。
GotenbergConvertException — 转换层异常类型。

完整合约位于 /integrations/gotenberg/configuration/ 与 /integrations/gotenberg/troubleshooting/。它涵盖传输层选择与异常清单。

另请参阅

/integrations/gotenberg/boot-and-discovery/ — 连接为何采用这种设计。
/integrations/gotenberg/quickstart/ — 一次带引导的初次转换。
/integrations/gotenberg/production-usage/ — 机密信息、重试、超时、可观测性。
/integrations/gotenberg/install/ — 软件包与 Gotenberg 服务安装。