NextPDF CodeIgniter 啟動與探索

概覽

CodeIgniter 4 會透過 Composer 套件探索，自動找到本套件的 Services 類別、helper 函式與 registrar。本頁說明確切的執行順序，以及控制此流程的組態。

CodeIgniter Services 探索的運作方式

CodeIgniter 4 解析服務時，會掃描每一個已探索到的 Config\Services 類別，找出名稱與所請求服務相符的靜態方法。因此當你的應用程式呼叫 service('pdf') 時，框架會找到第一個宣告了 pdf 方法的已探索 Services 類別，並呼叫它。

探索行為由 Config\Modules 管控：

• $enabled — 自動探索的主開關。預設為 true。
• $discoverInComposer — 將探索範圍延伸到各個 Composer 套件。預設為 true。正是這個旗標讓框架能找到 nextpdf/codeigniter。
• $composerPackages — 對 Composer 套件集合套用的選用 only / exclude 篩選器。
• $aliases — 參與探索的元素類型。框架預設包含 services 與 registrars，本套件會同時用到這兩者。

套件類別為 NextPDF\CodeIgniter\Config\Services。Composer 會把 PSR-4 前綴 NextPDF\CodeIgniter\ 對映到 src/CodeIgniter/。完整限定類別名稱必須包含頂層命名空間（PSR-4 §x1.x2.p5，規範性 MUST）。命名空間前綴會對映到基底目錄，因此該類別會解析到對應的檔案（PSR-4 §x1.x3）。

啟動順序

1. Composer 自動載入。 Composer 會註冊 PSR-4 對映與 files 自動載入項目。helper 檔案 src/CodeIgniter/Helpers/pdf_helper.php 會在此載入。
2. 框架啟動程序。 CodeIgniter 會讀取 Config\Modules。啟用探索時，它會跨各 Composer 套件建立已探索元素清單。
3. Registrar 探索。 框架會收集 Registrar 類別。套件的 Registrar::Autoload() 會把 pdf helper 通報給 CodeIgniter 的 helper 載入器。
4. 首次呼叫時的服務解析。 服務工廠採延遲建立。第一次呼叫 service('pdf') 或 Services::pdf() 時，才會執行工廠。共用服務會在定位器上以程序為單位快取。

容器繫結

CodeIgniter 4 沒有 PSR-11 容器。這裡所謂的「繫結」，就是 Services 類別上的靜態工廠方法。每個方法都接受一個 bool $getShared 參數：

服務	預設共用	說明
fontRegistry	是	先預熱後鎖定。
imageRegistry	是	有界的 LRU 快取。
documentFactory	是	無狀態。
pdfDocument	否	每次呼叫都重新建立。
pdf	否	每次呼叫都重新建立。
tsaClient	是	null，表示未設定 TSA URL。
pdfSigner	否	null，表示已停用簽章。

共用實例存放在 CodeIgniter 的 BaseService 實例快取中，作用範圍以程序為單位。框架的測試載具會透過 BaseService::reset() 清除該快取，而本套件的功能測試正是依賴各測試案例之間的這個重設。

組態解析順序

有效組態會依下列順序解析：

1. 套件預設值位於 NextPDF\CodeIgniter\Config\NextPdf。
2. 應用程式類別 Config\NextPdf（若存在）會擴充套件類別。CodeIgniter 會改載入它，以取代套件預設值。
3. 由 BaseConfig 套用的環境覆寫，會以小寫短類別名稱 nextpdf 為鍵（點分巢狀鍵，或完整限定類別形式）。

應用程式的組態擴充檔只宣告一個類別，且不執行任何副作用。這讓它符合 PSR-1 的預期：一個檔案要嘛宣告符號，要嘛執行有副作用的邏輯，但不能兩者兼具（PSR-1 §x1.x1.p3）。helper 檔案則是刻意安排作為有副作用的對應部分。它宣告全域的 pdf() 與 pdf_document() 函式，而且每個函式都以 function_exists 檢查加以保護，因此重複載入也安全。

診斷

• composer dump-autoload — 升級後用來重建 PSR-4 對映與 files 自動載入清單。
• 最快的探索探測方式，是撰寫一個呼叫 Services::pdfDocument(false) 的控制器，並斷言它回傳 Document。
• 檢查 vendor/composer/autoload_files.php 以確認 helper 檔案已註冊。
• 失敗與成因的對照，請見 /integrations/codeigniter/troubleshooting/ 一節。

符合性

• 完整限定類別名稱必須包含頂層命名空間（PSR-4 Autoloader §x1.x2.p5）。
• 命名空間前綴會對映到類別路徑的基底目錄（PSR-4 Autoloader §x1.x3）。
• 一個檔案要嘛宣告符號、要嘛造成副作用 — 也就是 helper 檔案的設計（PSR-1 Basic Coding Standard §x1.x1.p3）。

另請參閱

• /integrations/codeigniter/integration/ — 串接參考與冒煙測試。
• /integrations/codeigniter/install/ — 安裝並驗證探索。
• /integrations/codeigniter/overview/ — 完整 API 介面。
• /integrations/codeigniter/troubleshooting/ — 探索失敗模式。