CodeIgniter API 參考

概覽

CodeIgniter 套件提供一組精簡、以控制器（controller）為主的介面：包裝單一文件的 Pdf 函式庫包裝器（搭配 Services::pdf() 與全域 pdf() 輔助函式）、把已建構文件轉成 DownloadResponse 的回應輔助函式（PdfResponse）、其背後的 Services 工廠（字型/影像登錄表、文件工廠、選用的簽章器與 TSA 用戶端）、NextPdf 組態類別，以及用於透過靜態建構器可呼叫項目非同步產生文件的 GeneratePdfJob。

從這裡開始：在控制器中呼叫 Services::pdf()（或 pdf() 輔助函式），用 $pdf->document() 加入內容，再回傳 $pdf->download('file.pdf')。這條路徑就涵蓋了最常見的任務。下方參考表格依介面分類整理；「常見任務」一節會先示範可直接執行的程式樣板。

常見任務

以下列出最常用的實作流程。每個範例都已對照 nextpdf/codeigniter 原始碼驗證過。

從控制器回傳可下載的 PDF，這是標準的繪製流程：

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, "Invoice #{$id}");

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

這段程式會 resolve（解析）取得一個全新的 Pdf，包裝一個全新的 Document，寫入一個儲存格，並回傳一個 DownloadResponse，帶有 attachment 處置方式與套件安全標頭。

在瀏覽器中內嵌預覽 PDF，使用同一個包裝器，改用 inline() 而非 download()：

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;

final class ReportController extends BaseController
{
    public function preview(): DownloadResponse
    {
        $pdf = pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly Report');

        return $pdf->inline('report.pdf');
    }
}

這段程式會使用全域 pdf() 輔助函式（等同於 Services::pdf()），並回傳一個 DownloadResponse，帶有 inline 處置方式，讓瀏覽器直接顯示 PDF，而不是下載。

在佇列上非同步產生 PDF，把帶有靜態建構器的 GeneratePdfJob 推入佇列：

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

service('queue')->push('pdf', GeneratePdfJob::class, [
    'builder'    => 'App\PdfBuilders\InvoiceBuilder::build',
    'outputPath' => WRITEPATH . 'pdfs/invoice-42.pdf',
    'context'    => ['invoice_id' => 42],
]);

這段程式會將產生作業排入佇列。worker 會驗證建構器（必須是 App\PdfBuilders\...::method 形式的靜態可呼叫項目）與輸出路徑（必須解析到 WRITEPATH/pdfs/ 底下並以 .pdf 結尾），建構一個全新文件，然後將其儲存。

函式庫包裝器

當你持有一個 Pdf 包裝器，並需要使用其回應或儲存方法時，請參考這張表格。

符號	參數	預設行為	回傳	擲回或失敗於	備註
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`：全新的核心文件。	包裝提供的文件，供單次回應或儲存作業使用。	`Pdf`	預期不會發生。	輸出之後請勿重複使用該包裝器。
`Pdf::document()`	無。	回傳被包裝的文件。	`NextPDF\Core\Document`	預期不會發生。	用它來呼叫核心的編寫 API。
`Pdf::inline(string $filename = 'document.pdf')`	`filename`：回應檔名。	瀏覽器內嵌（inline）處置方式。	`CodeIgniter\HTTP\DownloadResponse`	核心序列化錯誤。	委派給 `PdfResponse::inline()`。
`Pdf::download(string $filename = 'document.pdf')`	`filename`：回應檔名。	瀏覽器附件（attachment）處置方式。	`DownloadResponse`	核心序列化錯誤。	委派給 `PdfResponse::download()`。
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`：回應檔名。	與其他 Framework（框架）套件維持 API 一致。	`DownloadResponse`	核心序列化錯誤。	CodeIgniter 原生即可處理二進位輸出。
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`：回應檔名。	與其他框架套件維持 API 一致。	`DownloadResponse`	核心序列化錯誤。	使用與非串流回應相同的大小控制項。
`Pdf::save(string $path)`	`path`：檔案系統的目標路徑。	寫出被包裝的文件。	`void`	檔案系統或核心寫入錯誤。	儲存前請先驗證儲存根目錄。

服務與輔助函式

當你需要特定的服務工廠或全域輔助函式，並想知道其共用行為與回傳型別時，請參考這張表格。

符號	參數	預設行為	回傳	擲回或失敗於	備註
`Services::fontRegistry(bool $getShared = true)`	`getShared`：CodeIgniter 共用服務旗標。	共用登錄表，會以已設定的字型預熱，然後鎖定。	`FontRegistryInterface`	`RuntimeException`：缺少擴充功能或字型路徑不安全時。	拒絕 `fontsPath` 中的串流包裝器與空位元組。
`Services::imageRegistry(bool $getShared = true)`	`getShared`：共用服務旗標。	共用且有界限的 LRU 影像登錄表。	`ImageRegistry`	預期不會發生。	快取大小由 `imageCacheMb` 控制。
`Services::documentFactory(bool $getShared = true)`	`getShared`：共用服務旗標。	使用共用登錄表的共用工廠。	`DocumentFactoryInterface`	登錄表設定錯誤。	工廠可重複使用；文件不可重複使用。
`Services::tsaClient(bool $getShared = true)`	`getShared`：共用服務旗標。	當 `tsa.url` 為空時回傳 `null`。	用戶端 `TsaClient	null`	HTTP 用戶端或 TSA 組態錯誤。
`Services::pdfSigner(bool $getShared = false)`	`getShared`：共用服務旗標。	當簽章功能停用時回傳 `null`。	簽章器介面 `SignerInterface	null`	憑證或簽章層級的錯誤。
`Services::pdfDocument(bool $getShared = false)`	`getShared`：共用服務旗標。	建立一個全新文件，套用預設值，並選擇性地設定 PDF/A 或 Artisan。	`Document`	選用的擴充功能或文件設定錯誤。	為了請求安全，請保留預設值 `false`。
`Services::pdf(bool $getShared = false)`	`getShared`：共用服務旗標。	建立一個全新的 `Pdf` 包裝器，包裝一個全新文件。	`NextPDF\CodeIgniter\Libraries\Pdf`	文件設定錯誤。	主要的面向控制器服務。
`Services::eInvoiceEmbedder()`	無。	除非存在 Premium Pro 電子發票嵌入器類別，否則回傳 `null`。	嵌入器介面 `EmbedderInterface	null`	選用套件的建構錯誤。
`Services::eInvoiceValidator()`	無。	除非存在 Premium Enterprise 驗證器類別，否則回傳 `null`。	驗證器介面 `ValidatorInterface	null`	選用套件的建構錯誤。
`Services::eInvoiceProfile()`	無。	已安裝 Premium Pro 時回傳 EN16931 設定檔。	設定檔介面 `ProfileInterface	null`	選用套件的錯誤。
`Services::schematronRunner()`	無。	除非存在 Premium Enterprise 的 Schematron 驗證器，否則回傳 `null`。	執行器介面 `SchematronRunnerInterface	null`	選用套件的建構錯誤。
`Registrar::Autoload()`	無。	將套件輔助函式加入 CodeIgniter 的 autoload 組態。	`array`	預期不會發生。	模組載入後會啟用 `pdf()` 與 `pdf_document()`。
`pdf()`	無。	呼叫 `Services::pdf(false)`。	`Pdf`	文件設定錯誤。	供控制器使用的便利輔助函式。
`pdf_document()`	無。	呼叫 `Services::pdfDocument(false)`。	`Document`	文件設定錯誤。	偏好使用核心文件 API 時的便利輔助函式。

HTTP 回應

當你已經持有一個已建構的 Document，並想自行建構 DownloadResponse 而不透過 Pdf 包裝器時，請參考這張表格。

符號	參數	預設行為	回傳	擲回或失敗於	備註
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`：已建構的文件；`filename`：回應檔名。	確保具備 `.pdf` 副檔名與內嵌處置方式。	`DownloadResponse`	核心序列化錯誤。	加入 PDF 內容類型與防禦性標頭。
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	與 `inline` 相同；處置方式為 attachment。	確保具備 `.pdf` 副檔名。	`DownloadResponse`	與 `inline` 相同。	用於瀏覽器下載。
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	與 `inline` 相同。	在 CI4 中與 `inline` 行為相同。	`DownloadResponse`	與 `inline` 相同。	為了跨框架 API 一致而存在。
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	與 `download` 相同。	在 CI4 中與 `download` 行為相同。	`DownloadResponse`	與 `download` 相同。	為了跨框架 API 一致而存在。

佇列工作

當你串接非同步產生流程，並需要精確掌握工作資料鍵與建構器可呼叫項目的契約時，請參考這張表格。

符號	參數	預設行為	回傳	擲回或失敗於	備註
`GeneratePdfJob::process()`	工作資料鍵：`builder`、`outputPath`，以及選用的 `context`。	省略時使用空的 context 陣列。	`void`	`InvalidArgumentException`：建構器或輸出路徑不安全時；以及核心寫入錯誤。	建構器必須是 `App\PdfBuilders\...\*::method`。
建構器可呼叫項目	`Document $doc`、`array $context`。	除了工作資料外沒有預設的 context。	`Document`	建構器特定的例外。	必須是靜態可呼叫項目，因為 CI4 佇列酬載是序列化後的資料。

組態

當你要在 NextPdf 組態類別變更預設值（頁面格式、路徑、簽章、TSA 或文件中繼資料）時，請參考這張表格。

屬性	型別	預設行為	備註
`pageFormat`	`string`	`A4`。	預設頁面格式。
`orientation`	`string`	`P`。	預設方向。
`unit`	`string`	`mm`。	預設單位。
`pdfa`	`string	null`	`null`。
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` 與 `WRITEPATH . 'cache/nextpdf'`。	請將路徑保留在應用程式可控制的儲存範圍內。
`signature`	`array`	以等級 `B-B` 停用。	憑證、金鑰、密碼、額外憑證與等級。
`tsa`	`array`	當 URL 為 `null` 時停用；逾時為 30 秒。	憑證資訊、mTLS 檔案、公鑰釘選與 HTTP 政策。
`ocspCache`	`array`	已啟用，TTL 為 86400 秒。	可用時供簽章驗證流程使用。
`preloadFonts`	`list<string>`	空的。	在登錄表鎖定之前預熱。
`imageCacheMb`	`int`	`50`。	控制行程生命週期內的影像快取。
`fontCacheLocking`	`bool`	`true`。	讓字型登錄表的變更不會影響請求處理。
`artisan`	`array`	除非已設定並安裝，否則 Chrome renderer（渲染器）預設為停用。	對映到 `ChromeRendererConfig::fromArray()`。
`defaults`	`array`	建立者為 `NextPDF`，作者留空，語言為 `en`，並搭配預設邊界與字型。	`Services::pdfDocument()` 只套用 `creator`、`language`，以及（非空時的）`author`；`margin_top`/`right`/`bottom`/`left`、`font_family`、`font_size`、`trim_box` 與 `bleed_box` 等鍵則是已定義但目前尚未套用的預設值。

開發備註

GeneratePdfJob 將輸出限制在 WRITEPATH . 'pdfs'，且要求以 .pdf 結尾。
位於 App\PdfBuilders 之外的建構器可呼叫項目會被拒絕，以避免從遭竄改的佇列酬載執行任意程式碼。
控制器流程請使用 service('pdf') 或套件輔助函式；長時間執行的產生作業則請使用佇列工作。