在 CodeIgniter 4 安裝 NextPDF

概覽

使用 Composer 安裝套件。CodeIgniter 4 會自行找到 Services 類別與輔助函式；你不需要手動註冊任何項目。

需求條件

此套件的 composer.json 宣告以下約束條件，該檔案才是權威來源。下表僅重述相同的約束條件。

相依套件	約束條件	備註
PHP	>=8.4 <9.0	此套件以 PHP 8.4 為目標版本。
nextpdf/core	^3.0 || ^5.2	NextPDF 引擎。
codeigniter4/framework	^4.6	已針對 CodeIgniter 4.7.0 驗證。
ext-mbstring	執行階段必要	每個行程驗證一次。
ext-zlib	執行階段必要	每個行程驗證一次。

以下選用套件宣告在 suggest 下：

套件	新增功能
nextpdf/artisan	Chrome CDP HTML renderer（渲染器；在文件建構時自動偵測）。
nextpdf/premium	NextPDF Pro 與 Enterprise：簽章、PDF/A、Factur-X。
codeigniter4/queue	透過 GeneratePdfJob 非同步產生 PDF。

安裝

安裝套件：

composer require nextpdf/codeigniter

Composer 會依上述約束條件解析（resolve） nextpdf/core 與 codeigniter4/framework。你不需要編輯服務供應者、套件包或啟動檔。

探索機制如何運作

當 Config\Modules::$discoverInComposer 為 true（也就是 Framework（框架）預設值）時，CodeIgniter 4 會掃描 Composer 套件以尋找框架元素。此套件隨附 NextPDF\CodeIgniter\Config\Services 類別。該類別位於 PSR-4 命名空間 NextPDF\CodeIgniter\ 之下，對映到 src/CodeIgniter/。Composer 的 PSR-4 自動載入會將該完整限定類別名稱轉換成檔案路徑。頂層命名空間是必要的（PSR-4 §x1.x2.p5，規範性 MUST）。命名空間前綴會對映到基底目錄，因此該類別會解析為對應的檔案（PSR-4 §x1.x3）。

套件的 Composer files 自動載入項目（src/CodeIgniter/Helpers/pdf_helper.php）會註冊這兩個輔助函式：pdf() 與 pdf_document()。套件的 Registrar 也會向 CodeIgniter 的輔助函式載入器宣告 pdf 輔助函式。完整流程請見 /integrations/codeigniter/boot-and-discovery/ 一節。

驗證安裝

確認 Composer 已解析出此套件：

composer show nextpdf/codeigniter

確認 CodeIgniter 已探索到 Services 類別。你可以在任一控制器中，或在簡短的 php spark 路由中，呼叫一個服務並斷言其型別：

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Config\Services;
use NextPDF\Core\Document;

$document = Services::pdfDocument(false);

// $document is a fresh NextPDF\Core\Document instance.
\assert($document instanceof Document);

若 Services::pdfDocument() 回傳一個 Document，表示探索正常運作。若該呼叫回傳 null，表示探索並未執行。請見 /integrations/codeigniter/troubleshooting/。

邊界情況與陷阱

• 若主機應用程式將 Config\Modules::$discoverInComposer 設為 false，請將 nextpdf/codeigniter 加入 $composerPackages['only'] 清單中。否則探索會略過此套件。
• 過時的 Composer 自動載入器可能會使 Services 類別無法被找到。升級後請執行 composer dump-autoload。
• 此套件僅將 codeigniter4/queue 宣告為開發相依套件。在正式環境會派送 GeneratePdfJob 的應用程式，必須自行要求安裝 codeigniter4/queue。

安全性注意事項

請透過 HTTPS 從 Packagist 安裝，並將解析出的版本鎖定在 composer.lock。此套件不會新增任何安裝時腳本。請見 /integrations/codeigniter/security-and-operations/。

符合性

• Composer 探索仰賴 PSR-4 自動載入。

另請參閱

• /integrations/codeigniter/overview/ — 此套件提供的功能。
• /integrations/codeigniter/quickstart/ — 在控制器中產生第一份 PDF。
• /integrations/codeigniter/configuration/ — 組態鍵與覆寫設定。
• /integrations/codeigniter/boot-and-discovery/ — 探索流程的詳細說明。