選擇整合方式
選擇整合方式
標題為「選擇整合方式」的區段本頁會把使用情境對應到負責處理該情境的整合方式。每一項建議都只依據套件的 composer.json 描述與其宣告用途，兩者皆直接讀自原始碼儲存庫。當兩種整合方式的適用範圍重疊時，本頁會點出區分兩者的關鍵因素，並把決定權交給你。
找出符合你情況的列，然後從那裡開始。
從這裡開始：你手上有什麼？
標題為「從這裡開始：你手上有什麼？」的區段| 你手上有…… | 使用 | 原因（驗證過的用途） |
|---|---|---|
| 一個 Laravel 12 應用程式 | nextpdf/laravel | Laravel Framework（框架）整合：service provider、facade，以及 PDF 回應輔助方法。 |
| 一個 Symfony 7 應用程式 | nextpdf/symfony | Symfony bundle（套件）：DI 服務與 PDF 回應輔助方法。 |
| 一個 CodeIgniter 4 應用程式 | nextpdf/codeigniter | CodeIgniter 4 服務、library（函式庫）包裝層，以及 PDF 回應輔助方法。 |
| 一個不依賴 framework 的 PHP 應用程式 | nextpdf/core（直接使用） | 不需要任何 framework 整合；這套引擎本身就是單純的 library。 |
| 一份需要瀏覽器 CSS 引擎處理的 HTML，而且你能執行 Chrome | nextpdf/artisan | Chrome CDP renderer（渲染器），適用於需要瀏覽器等級 CSS 版面配置的 HTML。 |
| 一份需要轉換的 Office 文件，例如 DOCX、XLSX 或 ODT | nextpdf/gotenberg | 透過 Gotenberg 微服務進行 Office 轉 PDF。 |
| 需要在沒有可操作瀏覽器行程的情況下進行渲染 | nextpdf/cloudflare | 在邊緣端透過 Cloudflare Browser Rendering API 進行 serverless（無伺服器）渲染。 |
| 針對舊版 PDF 函式庫撰寫的程式碼 | nextpdf/compat-legacy | 舊版 PDF 函式庫的 shim（相容層）；無需改寫呼叫位置就能呼叫 NextPDF。 |
| 卡在 PHP 8.1 / 7.4 的執行環境 | nextpdf/backport-builder | Rector 降階管線，會替引擎建構出一份 8.1 / 7.4 的目標版本。 |
| 遠端呼叫端、另一種程式語言，或一套 AI 系統 | nextpdf/server | NextPDF Connect：供遠端執行使用的 REST、gRPC 與 Model Context Protocol 介面。 |
當兩種整合方式都可能適用時
標題為「當兩種整合方式都可能適用時」的區段把 HTML 渲染成 PDF：Artisan、Gotenberg、Cloudflare 與核心的取捨
標題為「把 HTML 渲染成 PDF：Artisan、Gotenberg、Cloudflare 與核心的取捨」的區段這三座 renderer 橋接都會把 markup（標記語言）轉成 PDF。差別在於運作方式，而非品質；因此，運作層面的差異才是決定因素。
nextpdf/artisan透過 Chrome DevTools Protocol 驅動 headless Chrome（無頭 Chrome）。它需要一個應用程式可以連線到的 Chrome 行程。當你能操作那個行程，而且文件需要瀏覽器 CSS 引擎時，就選它。nextpdf/gotenberg透過 HTTP 呼叫跨行程的 Gotenberg 微服務。當渲染必須隔離在獨立服務中，或輸入是一份 Office 文件時，就選它。在這三者之中，只有 Gotenberg 的宣告用途包含 Office 轉 PDF。nextpdf/cloudflare呼叫 Cloudflare Browser Rendering API。當你想要 edge/serverless 渲染，而且不想執行或修補任何瀏覽器行程時，就選它。- 行程內的 NextPDF 核心 HTML 管線 完全不需要上述任何一項。只有當行程內管線無法達到文件所需的版面忠實度或行程隔離要求時，才使用 renderer 橋接。使用橋接代表你刻意把那一步交由外部處理，而不是預設路徑。
這兩座 HTTP 橋接（nextpdf/gotenberg、nextpdf/cloudflare）都需要一個由主機端提供的 PSR-18 HTTP client。它們的 recipe（範例）會把傳輸失敗與非成功的 HTTP 狀態視為兩種不同結果。
轉換一份 Office 文件
標題為「轉換一份 Office 文件」的區段nextpdf/gotenberg 是經過驗證，且在 composer.json 描述中明確點名 Office 轉 PDF 的整合方式。其他幾座 renderer 橋接描述的是 HTML 渲染，而非 Office 輸入。如果來源是 DOCX/XLSX/ODT，這就是適合你的選擇。
從舊版 PDF 函式庫遷移出來
標題為「從舊版 PDF 函式庫遷移出來」的區段依其宣告用途，nextpdf/compat-legacy 是給針對舊版 PDF 函式庫撰寫的程式碼使用的相容層。它讓既有呼叫位置在改寫完成之前就能連到 NextPDF。請把它視為具有明確移除時程的遷移過渡輔助，而不是長期的執行期相依套件。新的程式碼則直接呼叫 nextpdf/core（或對應的 framework 整合）。
在 PHP 8.1 或 7.4 上執行
標題為「在 PHP 8.1 或 7.4 上執行」的區段每個生態系套件都宣告 PHP >=8.4 <9.0。nextpdf/backport-builder 正是為了這項限制而存在：它宣告的用途是一條 Rector 降階管線，會建構出一份 PHP 8.1+（以及一份 7.4 目標）的產出物。它是建構工具，不是你應用程式的執行期相依套件。請先執行這個建構器，產生降階後的引擎，再部署那份引擎。
非 PHP 呼叫端或 AI Agent（代理）
標題為「非 PHP 呼叫端或 AI Agent（代理）」的區段nextpdf/server（NextPDF Connect）透過 REST API、gRPC 服務與 Model Context Protocol 把引擎對外開放。當呼叫端位於遠端、使用另一種程式語言，或是一套使用工具 endpoint 而非 PHP 函式庫的 AI 系統時，就選它。在同一行程內的 PHP 應用程式則應改用 nextpdf/core 或 framework 整合，以免付出一次網路往返的代價。
同時使用多種整合方式
標題為「同時使用多種整合方式」的區段framework 整合與 renderer 橋接運作在不同層級，所以你可以同時安裝兩者。framework 整合負責容器接線與 HTTP 回應；renderer 橋接負責渲染 backend（後端）。當你要 resolve（解析）一組合併後的相依集合時，請檢查每個套件各自接受哪些 nextpdf/core 版本。關於這一點，整合 Cookbook Index（索引） 裡的核心版本限制參考才是判準。各種組合的 recipe 位於對應儲存庫中，並從該索引連出。
另請參閱
標題為「另請參閱」的區段- 整合 Cookbook — 套件與核心版本限制參考，以及 recipe 連結索引。
- Recipe 慣例 — 每個可執行 recipe 都遵循的契約。