CodeIgniter 開發者指南

概覽

CodeIgniter 套件提供服務工廠（factory）、輔助函式，以及一個包覆單一文件的精簡 Pdf 函式庫包裝層。這個包裝層適合用在控制器（controller）中。佇列工作則改用靜態建構器 callable，因為 CodeIgniter 的佇列負載是序列化後的資料。

當你要設計以 nextpdf/codeigniter 為核心的控制器流程、服務、佇列建構器或測試時，請使用本指南。

架構邊界

層級	負責方	職責	不要放在這裡
控制器	應用程式	執行授權、呼叫建構器或服務，然後回傳 `DownloadResponse`。	共用的版面邏輯。
函式庫包裝層	`nextpdf/codeigniter`	包覆單一 `Document`，並提供 response/save 輔助方法。	長期保存用的文件儲存。
服務工廠	`nextpdf/codeigniter`	建立共用登錄表與全新的文件。	業務專屬的儲存根目錄。
佇列建構器	應用程式	根據靜態 callable 輸入建構文件。	請求物件或無法序列化的狀態。
核心引擎	`nextpdf/nextpdf`	建構並序列化 PDF。	CodeIgniter 回應或佇列政策。

執行期生命週期

階段	行為	開發者動作
自動載入註冊	`Registrar::Autoload()` 為模組註冊輔助函式載入流程。	透過 CodeIgniter 組態載入此模組。
服務 resolve（解析）	`Services::pdf()` 預設回傳包覆全新文件的包裝層。	每個請求只解析一次。
文件撰寫	應用程式碼透過 `Pdf::document()` 呼叫核心文件 API。	將建構文件的程式碼放在服務或建構器中。
回應	`PdfResponse` 會回傳 `DownloadResponse`。	讓套件設定 PDF 標頭。
佇列執行	`GeneratePdfJob::process()` 會驗證建構器與輸出路徑，然後存檔。	將佇列建構器放在 `App\PdfBuilders` 底下。

建議的應用程式結構

路徑	用途
`app/PdfBuilders/*`	可供 `GeneratePdfJob` 接受的靜態、佇列安全建構器。
`app/Libraries/*`	圍繞重複文件工作流程的選用應用程式包裝層。
`app/Services/*`	領域資料的擷取與儲存政策。
`app/Config/NextPdf.php`	應用程式層對套件組態的覆寫。
`tests/app/PdfBuilders/*`	建構器與佇列負載的測試。

流程短時，直接使用套件提供的輔助函式。當文件建構邏輯屬於某個應直接測試的類別時，請改用明確的服務呼叫。

<?php

namespace App\Controllers;

final class InvoiceController extends BaseController
{
    public function download(int $id)
    {
        $pdf = pdf();
        $pdf->document()
            ->setTitle('Invoice ' . $id)
            ->addPage()
            ->writeHtml('<h1>Invoice ' . $id . '</h1>');

        return $pdf->download('invoice-' . $id . '.pdf');
    }
}

佇列建構器模式

佇列建構器應該是靜態、具決定性，並放在 App\PdfBuilders 底下。請讓 context 陣列保持足夠精簡，方便序列化與稽核。

<?php

namespace App\PdfBuilders;

use NextPDF\Core\Document;

final class InvoiceBuilder
{
    public static function build(Document $document, array $context): Document
    {
        $document->setTitle((string) $context['title'])
            ->addPage()
            ->writeHtml((string) $context['html']);

        return $document;
    }
}

這個工作會將輸出限制在已設定的應用程式 PDF 目錄內。如果你的應用程式需要租戶專屬的儲存，請將該政策放進單一服務，並在佇列派送前先測試它。

擴充點

擴充點	用於	限制
`Services::pdfDocument()`	自訂文件建立方式。	必須回傳一份全新的文件。
`Services::fontRegistry()`	字型暖機與登錄表存取。	拒絕不安全的路徑，並在暖機後保持登錄表鎖定。
`Services::pdfSigner()`	選用的數位簽章。	當簽章功能停用時回傳 `null`。
`NextPDF\CodeIgniter\Libraries\Pdf`	供控制器使用的包裝層。	一個包裝層對應一份文件。
`App\PdfBuilders::*`	佇列安全的文件建構器。	必須是靜態 callable 字串。
`app/Config/NextPdf.php`	應用程式預設值與整合設定。	讓正式環境值保持明確。

開發工作流程

先從呼叫 pdf() 或 service('pdf') 的控制器開始。
將重複的文件建構邏輯移到 app/PdfBuilders 或某個應用程式服務。
當文件在請求路徑產生得太慢時，請改用 GeneratePdfJob。
讓佇列的 context 保持可序列化且精簡。
除非你刻意擴充政策，否則請將輸出存放在核准的 PDF 儲存根目錄底下。
為輔助函式、服務、佇列負載與不安全路徑加上測試。

失敗處理

失敗情況	應該在哪裡處理	建議的回應方式
缺少擴充功能或字型路徑不安全	服務工廠。	在服務解析階段快速失敗（fail fast）。
無效的建構器 callable	佇列工作的驗證。	拒絕該工作，並在不洩漏機密的情況下記錄建構器字串。
不安全的輸出路徑	儲存服務與佇列工作。	在派送前拒絕，並保留工作本身的驗證。
回應序列化錯誤	控制器或 Framework（框架）的錯誤處理。	不要送出不完整的回應內容。
選用的 Premium 類別不可用	服務方法的回傳值。	使用選用的電子發票功能前，請先明確處理 `null`。

安全的預設值

關注項目	預設值	何時該覆寫
佇列建構器命名空間	`App\PdfBuilders`。	除非你也同步更新安全政策，否則維持預設值。
輸出根目錄	`WRITEPATH/pdfs`。	只有在採用更嚴格的允許清單時才覆寫。
回應檔名	`document.pdf`。	使用經過清理的業務檔名。
串流方法	與其他框架保持 API 一致。	在 CodeIgniter 中，不要依賴串流作為記憶體邊界。
文件服務	預設為全新文件。	不要在請求程式碼中要求使用共用文件。

測試檢查清單

服務測試會斷言每次 Services::pdf() 解析都回傳一份獨立的文件。
輔助函式測試會斷言 pdf() 與 pdf_document() 都回傳全新的物件。
回應測試會斷言標頭與檔名正規化。
佇列測試會涵蓋無效的建構器字串與不安全的輸出路徑。
建構器測試會以具代表性的 context 資料執行。
組態測試會涵蓋字型路徑、快取路徑、簽章停用，以及 TSA 停用等狀態。