安装 NextPDF Gotenberg

速览

安装桥接器包含两部分。第一部分是 PHP 包及其 PSR HTTP 依赖，需要通过 Composer 安装。第二部分是该包调用的 Gotenberg 服务。桥接器会把工作交给该服务来执行转换，因此在 Gotenberg 实例可达之前，它无法转换任何内容。

在编写任何转换代码之前，先完成这两部分。

要求

要求项	约束	原因
PHP	>=8.4 <9.0	该包在 composer.json 中声明此范围。
NextPDF 核心	^3.0	在 composer.json 中声明的直接依赖。
PSR-18 HTTP 客户端	^1.0	桥接器通过注入的 Psr\Http\Client\ClientInterface 发送请求。
PSR-17 HTTP 工厂	^1.1	桥接器通过注入的 PSR-17 工厂构建请求和流。
PSR-3 日志记录器	^3.0（可选）	可注入日志记录器，用于请求级别的调试日志。
Gotenberg 服务	可通过 HTTPS 访问	转换由外部服务执行，而非由本包执行。

桥接器不捆绑 PSR-18 客户端或 PSR-17 工厂。你可以自行选择实现。例如，你可以将基于 Guzzle 的客户端与其 PSR-17 工厂搭配，也可以将 Symfony HTTP 客户端与 nyholm/psr7 搭配。只要实现符合相关 PSR 契约，就可以使用；桥接器只依赖接口，不依赖特定库。

步骤 1 — 安装该包

使用 Composer 添加该包：

composer require nextpdf/gotenberg

这会解析 nextpdf/core ^3.0 以及 PSR HTTP 契约：psr/http-client、psr/http-factory 和 psr/log。它不会安装具体的 HTTP 客户端。

步骤 2 — 安装 PSR-18 客户端和 PSR-17 工厂

安装一个 PSR-18 客户端和一套匹配的 PSR-17 工厂。 使用 Guzzle：

composer require guzzlehttp/guzzle guzzlehttp/psr7

或者使用 Symfony HTTP 客户端和 Nyholm PSR-7：

composer require symfony/http-client nyholm/psr7

桥接器会把它们作为构造函数参数接收。它从不自行构建 HTTP 客户端。因此，选择权完全在你手中，并在装配桥接器时确定。有关构造函数的形态，请参阅 /integrations/gotenberg/configuration/；有关完整的装配示例，请参阅 /integrations/gotenberg/quickstart/。

步骤 3 — 搭建 Gotenberg 服务

桥接器会调用 Gotenberg 的 LibreOffice 转换路由，因此你需要一个桥接器可访问的 Gotenberg 实例。上游项目发布了一个容器镜像。本地开发的标准命令是：

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

这会通过纯 HTTP 在端口 3000 上暴露 Gotenberg，仅适用于本地开发。桥接器要求配置的 API URL 使用 HTTPS。它会在发送任何请求之前拒绝纯 http://。对于本地实验以外的任何场景，请将 Gotenberg 放在终止 TLS 的反向代理或服务网格之后，然后将桥接器指向该 HTTPS 端点。/integrations/gotenberg/security-and-operations/ 涵盖生产部署形态、网络暴露和身份验证。

此处所示的镜像标签（gotenberg/gotenberg:8）是上游 Gotenberg 主版本线。本项目自身的 README 和集成基线引用该版本线。在生产环境中，请固定到具体的补丁标签，而不是跟踪会移动的主版本标签。另请校验路由路径（/forms/libreoffice/convert、/health），并对照你部署的 Gotenberg 版本进行确认。桥接器假定这两条路径存在，除此之外不对该服务做出任何其他假设。

步骤 4 — 验证装配

至此，该包和一个 HTTP 客户端已安装，且 Gotenberg 可通过 HTTPS 访问。在尝试真正的转换之前，请使用内置健康探针确认桥接器可以访问该服务：

<?php

declare(strict_types=1);

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

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

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
);

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

isAvailable() 会先验证配置的 URL。对于空 URL、非 HTTPS URL 或私有地址 URL，它会返回 false，且不会产生任何网络流量。随后，它会向 <apiUrl>/health 发送一个 HEAD 请求，并在状态码低于 500 时报告该服务可用。网络错误会被捕获并报告为不可用，而不会被抛出。

版本说明

本文档描述的是该包的 ^3.0 版本线。该版本线与 composer.json 的要求以及 SECURITY.md 支持矩阵一致，其中 3.x 受支持，而 2.x 不受支持。仓库内骨架页面中较早的 0.x 引用早于 3.0 版本线，应以 composer.json 约束为准。

另请参阅

• /integrations/gotenberg/overview/ — 桥接器的作用及其支持转换的格式。
• /integrations/gotenberg/configuration/ — 每一个构造函数参数和配置字段。
• /integrations/gotenberg/quickstart/ — 一个完整、可运行的首次转换。
• /integrations/gotenberg/security-and-operations/ — 如何安全运维 Gotenberg 依赖。
• /integrations/gotenberg/boot-and-discovery/ — 框架自动装配。