整合 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 的 service container（容器）與請求生命週期：
nextpdf/laravel、nextpdf/symfony、nextpdf/codeigniter。你安裝其中一個、resolve（解析）出服務，然後回傳 PDF response。 - renderer bridge（渲染器橋接） 把 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，而你想讓 NextPDF 從 container resolve 出來並以 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。當呼叫端位於遠端、以另一種語言撰寫，或 AI 系統需要的是工具 endpoint（而不是 PHP 函式庫）時，就用它。範例：[[/integrations/connect/quickstart/]]。
範例連結如何解析
標題為「範例連結如何解析」的區段上方每一個 [[…]] placeholder，都是指向頁面的前向參照；該頁面由整合自己的 repository 在 docs/public/ 之下撰寫，並由 aggregator 拉進本站。目標 slug 遵循同一套約定：
/integrations/<integration>/<recipe>/上方「套件與 core 約束參考」表中的 <integration> token 是直接取自套件名稱的短名稱；表內每列都提供其中一個短名稱。每個整合出貨的第一個 recipe 都命名為 quickstart；後續範例會使用額外的 <recipe> 區段，置於同一個 <integration> 根之下。在某個目標頁面聚合進來之前，它的連結是一個 placeholder，無法解析。這份索引不對任何目標頁面提出行為層面的主張。它只記錄從 composer.json 驗證過的套件事實，以及每個 repository 的範例將佔用的 slug。