為 CodeIgniter 4 設定 NextPDF

快速總覽

組態位於 NextPDF\CodeIgniter\Config\NextPdf，它是 CodeIgniter 的 BaseConfig 子類別。你可以在 app/Config/ 中擴充這個類別來覆寫值，或設定 .env 鍵並加上 nextpdf. 前綴。若不做任何設定，預設值即可運作。

概念總覽

NextPdf 是一個具型別的 BaseConfig，並刻意設計為 非 final。在 CodeIgniter 的慣例中，應用程式組態會擴充套件類別，讓應用程式可以覆寫預設值。CodeIgniter 建構組態時，BaseConfig 會針對每個 public 屬性解析（resolve）環境覆寫值；巢狀陣列鍵也包含在這個解析流程中。

預設字型與快取路徑使用 CodeIgniter 的 WRITEPATH 常數：WRITEPATH . 'fonts' 與 WRITEPATH . 'cache/nextpdf'。

組態鍵

下列每個鍵都是 NextPdf 的 public 屬性。預設值皆已依套件原始碼驗證。

頁面與文件預設值

項目	型別	預設值	說明
`pageFormat`	`string`	`A4`	頁面格式。
`orientation`	`string`	`P`	`P` 為直向，`L` 為橫向。
`unit`	`string`	`mm`	量測單位。
`defaults.creator`	`string`	`NextPDF`	PDF 建立者後設資料。
`defaults.author`	`string`	`''`	作者後設資料；為空時略過。
`defaults.language`	`string`	`en`	文件語言標記。
`defaults.margin_top`	`float`	`10.0`	上邊界。
`defaults.margin_right`	`float`	`10.0`	右邊界。
`defaults.margin_bottom`	`float`	`10.0`	下邊界。
`defaults.margin_left`	`float`	`10.0`	左邊界。
`defaults.font_family`	`string`	`dejavusans`	預設字型家族。
`defaults.font_size`	`float`	`12.0`	預設字級。
`defaults.trim_box`	`list<float>\|null`	`null`	設定後會作為裁切框（trim box）。
`defaults.bleed_box`	`list<float>\|null`	`null`	設定後會作為出血框（bleed box）。

套件會將 defaults.creator 與 defaults.language 套用到每一份文件；而 defaults.author 只有在值非空時才會套用。

路徑與快取

項目	型別	預設值	說明
`fontsPath`	`string`	`WRITEPATH/fonts`	字型檔案目錄。
`cachePath`	`string`	`WRITEPATH/cache/nextpdf`	快取目錄。
`preloadFonts`	`list<string>`	`[]`	啟動時預熱的絕對字型路徑。
`imageCacheMb`	`int`	`50`	影像 LRU 快取預算，以 MB 為單位。
`fontCacheLocking`	`bool`	`true`	預熱後鎖定字型快取。

字型登錄會拒絕包含 stream wrapper（://）或 null byte 的 fontsPath。這類拒絕會引發執行階段錯誤。詳見 /integrations/codeigniter/security-and-operations/.

封存與色彩（NextPDF Pro）

項目	型別	預設值	說明
`pdfa`	`string\|null`	`null`	PDF/A 版本：`4`、`4e`、`4f`。
`iccProfile.rgb`	`string\|null`	`null`	RGB ICC 描述檔路徑。
`iccProfile.cmyk`	`string\|null`	`null`	CMYK ICC 描述檔路徑。

只有在安裝 NextPDF Pro 且封存能力可用時，pdfa 才會生效；此時封存能力才算就緒。若只有 core，這個鍵會被忽略。

數位簽章（NextPDF Pro / Enterprise）

項目	型別	預設值	說明
`signature.enabled`	`bool`	`false`	啟用簽章服務。
`signature.certificate`	`string\|null`	`null`	憑證檔案路徑。
`signature.private_key`	`string\|null`	`null`	私密金鑰檔案路徑。
`signature.password`	`string`	`''`	私密金鑰密碼。
`signature.extra_certs`	`list<string>`	`[]`	額外的鏈結憑證路徑。
`signature.level`	`string`	`B-B`	簽章等級識別碼。

Services::pdfSigner() 會回傳 null，除非 signature.enabled 為 true，且 signature.certificate 非空。預設等級是 B-B。NextPDF Pro 提供 B-B 基準簽章。長期驗證等級屬於另一項 Enterprise 能力，相關內容記錄在 Premium 參考文件中，不在此處說明。

PAdES B-T 由 Core 引擎產生。CodeIgniter 整合本身不會加上 B-T，且 Pro 僅提供 B-B 基準。本文件會在 Pro B-T 推出時（若有）一併更新。

時間戳記憑證機構（TSA）

項目	型別	預設值	說明
`tsa.url`	`string\|null`	`null`	TSA 端點 URL。
`tsa.username`	`string`	`''`	TSA 基本驗證使用者名稱。
`tsa.password`	`string`	`''`	TSA 基本驗證密碼。
`tsa.cert`	`string\|null`	`null`	用戶端憑證路徑。
`tsa.key`	`string\|null`	`null`	用戶端金鑰路徑。
`tsa.timeout`	`int`	`30`	請求逾時秒數。
`tsa.pinned_public_keys`	`list<string>`	`[]`	已釘選的 TSA 公開金鑰。
`tsa.warn_on_key_rotation`	`bool`	`true`	TSA 金鑰輪替時發出警告。
`tsa.allow_insecure_http`	`bool`	`false`	允許以明文 HTTP 連線到 TSA。

當 tsa.url 為 null 或空字串時，Services::tsaClient() 會回傳 null。選用需要時間戳記的簽章等級時，簽章器會自動掛上 TSA 用戶端。

OCSP 快取

項目	型別	預設值	說明
`ocspCache.enabled`	`bool`	`true`	啟用 OCSP 回應快取。
`ocspCache.ttl`	`int`	`86400`	快取存活時間（TTL），以秒為單位。
`ocspCache.directory`	`string\|null`	`null`	快取目錄；為 null 時使用引擎預設值。

Chrome HTML renderer（渲染器）（NextPDF Artisan）

項目	型別	預設值	說明
`artisan.chrome_binary`	`string\|null`	`null`	Chrome / Chromium 二進位檔路徑。
`artisan.render_timeout`	`int`	`30`	渲染逾時秒數。
`artisan.default_css`	`string`	`''`	預設樣式表。
`artisan.no_sandbox`	`bool`	`false`	將 `--no-sandbox` 傳給 Chrome。
`artisan.max_html_size`	`int`	`5000000`	輸入 HTML 的大小上限，以位元組為單位。

只有在設定了 artisan.chrome_binary 且安裝了 nextpdf/artisan 時，才會在文件上設定 Chrome renderer。

覆寫設定，使用 `.env`

BaseConfig 會逐一解析各屬性的環境覆寫值。查找鍵是小寫短類別名稱 nextpdf，後接屬性路徑。巢狀陣列鍵以點號定址；點號與底線兩種形式都可接受。

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

前綴是小寫短類別名稱；即使類別寫成 NextPdf，前綴仍維持 nextpdf。完整限定形式（NextPDF\CodeIgniter\Config\NextPdf.fontsPath）也可接受。

以擴充類別的方式覆寫

若要使用具型別且納入版本控制的組態，請在 app/Config/ 中擴充套件類別。CodeIgniter 會載入應用程式類別，以取代套件預設值。這個檔案只宣告一個類別，不產生任何副作用。這樣可符合 PSR-1 的期望：一個檔案要嘛宣告符號，要嘛執行有副作用的邏輯，但不可兩者兼有（PSR-1 §x1.x1.p3）。

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

邊界案例與陷阱

以 .env 覆寫單一巢狀鍵時，只會覆寫該鍵；陣列的其餘部分維持預設值。
.env 的值都是字串。CodeIgniter 會轉換 true / false 與數字字串。若值必須維持字面字串，請加上引號。
如果擴充類別時只提供部分 defaults 陣列，仍會取代整個陣列。請納入每一個鍵，如上所示。

安全性注意事項

請勿將憑證與金鑰路徑放進原始碼版本控制。請透過 .env 或機密管理工具提供這些路徑。在正式環境中，tsa.allow_insecure_http 必須維持 false。詳見 /integrations/codeigniter/security-and-operations/.

符合性

應用程式的組態擴充檔案只宣告一個類別，且沒有副作用（PSR-1 §x1.x1.p3）。

商業脈絡

NextPDF core 採用 Apache-2.0 授權。只有在安裝 NextPDF Pro 或 Enterprise 時，signature.* 與 pdfa 鍵才會生效。CodeIgniter 套件會公開對應的服務方法；在安裝對應的 Premium 套件之前，這些方法都會回傳 null。詳見 </get-license/?intent=codeigniter-signing>。

另請參閱

/integrations/codeigniter/install/ — 安裝套件。
/integrations/codeigniter/quickstart/ — 第一份 PDF。
/integrations/codeigniter/production-usage/ — 透過 DI 接線的控制器與佇列工作。
/integrations/codeigniter/security-and-operations/ — 強化簽章與路徑組態。