集成 cookbook
集成 cookbook
标题为“集成 cookbook”的章节NextPDF core 使用 PHP 生成 PDF 2.0。生态系统中的这九个集成包，会把这套引擎接入 Framework（框架）、渲染后端、既有旧代码、构建流程或网络服务。本页说明每个集成的用途，记录各自的包名与 core 版本约束（直接读取自各包的 composer.json），并链接到各集成的 recipe（示例）——这些示例会在来源 repository 发布其 docs/public/ 树时 aggregate（聚合）到此处。
本页是一份 Index（索引），因此不对任何集成作行为层面的主张。每个集成的 recipe 都由其所属 repository 维护。aggregator（文件聚合器）会把它们拉入本站；在某个示例聚合进来之前，下方链接指向的是一个 placeholder（占位符）。如需按使用场景选择集成，请参阅 选择一个整合。如需了解每个可执行示例遵循的约定，请参阅 范例约定。
五种集成形态
标题为“五种集成形态”的章节这九个包可归为五种形态。形态用于说明某个集成解决的是哪一类问题。
- 框架集成 把 NextPDF 接入应用程序 framework 的服务 container（容器）与请求生命周期：
nextpdf/laravel、nextpdf/symfony、nextpdf/codeigniter。你安装其中一个，从中 resolve（解析）出一个服务，然后返回一份 PDF response。 - renderer（渲染器）桥接 把 HTML 转 PDF 或 Office 转 PDF 这一步委托给外部渲染后端，而不是进程内管线：
nextpdf/artisan（通过 Chrome DevTools Protocol 操作 headless Chrome）、nextpdf/gotenberg（一个 Gotenberg microservice）、nextpdf/cloudflare（在 edge 边缘执行的 Cloudflare Browser Rendering）。 - 一个兼容性 shim（兼容层） 让面向旧版 PDF 函数库编写的代码，无须改写即可调用 NextPDF：
nextpdf/compat-legacy。 - 一个构建工具 为无法执行 8.4 的运行环境，生成 NextPDF 的 PHP 8.1 / 7.4 backport：
nextpdf/backport-builder。 - 一个网络服务 通过 REST、gRPC 与 Model Context Protocol，把 NextPDF 开放给 AI 系统与远端调用端：
nextpdf/server（以 NextPDF Connect 名义分发）。
以 HTTP 通信的 renderer bridge（nextpdf/gotenberg、nextpdf/cloudflare，以及 nextpdf/laravel 中的 HTTP-client 路径）依赖宿主应用程序提供的 PSR-18 HTTP client。按照适用条款 PSR-18 §4，PSR-18 client 只有在完全无法发送请求时，才会抛出带类型的 client exception。HTTP 4xx 或 5xx 响应是正常返回值，而不是异常——同一条 PSR-18 §4 条款也作此规定。调用远端 renderer 的示例，会将传输错误与非成功状态作为两种独立情况分别处理。
包与 core 约束参考
标题为“包与 core 约束参考”的章节下方每个值都读取自指定包的 composer.json（权威来源）。core 约束即该包声明的 nextpdf/core 需求。nextpdf/backport-builder 并未声明任何 nextpdf/core 需求，因为它是转换引擎的源代码，而不是在运行时依赖引擎。
| 集成 | 包 | 形态 | core 约束 | 示例 |
|---|---|---|---|---|
| Laravel | nextpdf/laravel | 框架 | ^3.0 || ^5.2 | Laravel quickstart 快速上手 [[/integrations/laravel/quickstart/]] |
| Symfony | nextpdf/symfony | 框架 | ^3.0 || ^5.2 | Symfony quickstart 快速上手 [[/integrations/symfony/quickstart/]] |
| CodeIgniter 4 | nextpdf/codeigniter | 框架 | ^3.0 || ^5.2 | CodeIgniter quickstart 快速上手 [[/integrations/codeigniter/quickstart/]] |
| Artisan（Chrome 浏览器） | nextpdf/artisan | renderer bridge（渲染器桥接） | ^3.0 || ^5.2 | Artisan quickstart 快速上手 [[/integrations/artisan/quickstart/]] |
| Gotenberg | nextpdf/gotenberg | 渲染器桥接 | ^3.0 | Gotenberg quickstart 快速上手 [[/integrations/gotenberg/quickstart/]] |
| Cloudflare | nextpdf/cloudflare | 渲染器桥接 | ^3.0 | Cloudflare quickstart 快速上手 [[/integrations/cloudflare/quickstart/]] |
| Compat（legacy 旧版） | nextpdf/compat-legacy | 兼容层 | ^3.0 | Compat-legacy quickstart 快速上手 [[/integrations/compat-legacy/quickstart/]] |
| backport builder（backport 构建器） | nextpdf/backport-builder | 构建工具 | 不适用 | Backport quickstart 快速上手 [[/integrations/backport/quickstart/]] |
| Connect（server 服务器） | nextpdf/server | 网络服务 | ^3.0 | Connect quickstart 快速上手 [[/integrations/connect/quickstart/]] |
NextPDF 以产品名 NextPDF Connect 分发 nextpdf/server；它的 recipe 放在 connect slug 之下。nextpdf/compat-legacy 属于 compat 家族；它的 recipe 放在 compat-legacy slug 之下。
每个包在自己的运行环境上都要求 PHP >=8.4 <9.0。nextpdf/backport-builder 的用途，正是生成可在 PHP 8.1（以及 7.4 目标）上执行的产物；在较旧运行环境上执行的是 backport 后的引擎，而不是这个构建器本身。
每个集成的用途
标题为“每个集成的用途”的章节框架集成
标题为“框架集成”的章节nextpdf/laravel—— 一个 Laravel 12 service provider、facade，以及 PDF response 辅助方法。当应用程序是 Laravel app，并且你希望从 container resolve 出 NextPDF、以 HTTP response 返回，同时不想手动接线时，就用它。示例：[[/integrations/laravel/quickstart/]]。nextpdf/symfony—— 一个 Symfony 7 bundle（包），带有依赖注入服务与 PDF response 辅助方法。当应用程序是 Symfony app 时就用它；这个 bundle 会把引擎注册为一个服务，并与symfony/http-foundation的 response 集成。示例：[[/integrations/symfony/quickstart/]]。nextpdf/codeigniter—— 一个 CodeIgniter 4 service、library wrapper，以及 PDF response 辅助方法。当应用程序是 CodeIgniter 4 app，并且你希望通过 framework 的 service locator 取用 NextPDF 时，就用它。示例：[[/integrations/codeigniter/quickstart/]]。
渲染器桥接
标题为“渲染器桥接”的章节nextpdf/artisan—— 一个通过 Chrome DevTools Protocol 运行的 headless Chrome renderer。当文件需要浏览器的 CSS engine 来达到进程内 HTML 管线未锁定的版面保真度，并且你可以在应用程序附近运行一个 Chrome 进程时，就用它。示例：[[/integrations/artisan/quickstart/]]。nextpdf/gotenberg—— 通过一个 Gotenberg microservice 执行 Office 转 PDF 与 HTML 转 PDF 转换。当输入是 Office 文件，或者渲染必须在另一个独立服务中以进程外方式执行时，就用它。它通过主机提供的 PSR-18 client 以 HTTP 通信。示例：[[/integrations/gotenberg/quickstart/]]。nextpdf/cloudflare—— 通过 Cloudflare Browser Rendering API 执行 serverless 无服务器渲染。当渲染应在 edge 边缘执行，并且不需要运维任何常驻浏览器进程时，就用它。它通过主机提供的 PSR-18 client 以 HTTP 通信。示例：[[/integrations/cloudflare/quickstart/]]。
兼容层
标题为“兼容层”的章节nextpdf/compat-legacy—— 一个兼容层，供面向旧版 PDF 函数库编写的代码使用。用它从既有代码调用 NextPDF，无须先改写调用点；它是迁移辅助工具，而不是永久依赖。示例：[[/integrations/compat-legacy/quickstart/]]。
建构工具
标题为“建构工具”的章节nextpdf/backport-builder—— 一个基于 Rector 的降版管线，用于生成 NextPDF 的 PHP 8.1（以及 7.4 目标）构建版本。当某个运行环境无法升级到 PHP 8.4，而你又必须在那里使用引擎时，就用它。它是构建基础设施，不会被加入应用程序的运行时依赖。示例：[[/integrations/backport/quickstart/]]。
网络服务
标题为“网络服务”的章节nextpdf/server（NextPDF Connect）—— 通过 REST API、gRPC 服务与 Model Context Protocol 开放 NextPDF。当调用端位于远端、使用另一种语言编写，或是需要工具 endpoint（而不是 PHP 函数库）的 AI 系统时，就用它。示例：[[/integrations/connect/quickstart/]]。
示例链接如何解析
标题为“示例链接如何解析”的章节上方每一个 [[…]] placeholder，都是一个指向页面的前向参照——该页面由集成自己的 repository 在 docs/public/ 之下撰写，并由 aggregator 拉入本站。目标 slug 遵循同一套约定：
/integrations/<integration>/<recipe>/上方「包与 core 约束参考」表中的 <integration> token 是直接取自包名的短名称；该表的每一列都会提供一个这样的短名称。每个集成发布的第一个 recipe 都命名为 quickstart；后续示例会使用额外的 <recipe> 区段，置于同一个 <integration> 根之下。在某个目标页面聚合进来之前，它的链接是一个 placeholder，无法解析。这份索引不对任何目标页面作行为层面的主张。它只记录经过 composer.json 验证的包事实，以及每个 repository 的示例将占用的 slug。