NextPDF CodeIgniter 整合

概覽

安裝套件後，CodeIgniter 4 會自動為你完成服務接線。本頁提供接線參考，涵蓋探索、繫結模型、發布組態，以及一個只需單一方法的冒煙測試，用來證明整合確實生效。

安裝

composer require nextpdf/codeigniter

你不需要修改 service provider，也不需要更動任何 bootstrap 檔案。已驗證的版本限制請見 /integrations/codeigniter/install/ 一節。

啟動/自動探索

CodeIgniter 4 會透過 Composer 套件探索找到此套件。當 Config\Modules::$discoverInComposer 為 true（也就是 framework 的預設值）時，就會進行探索。PSR-4 前綴 NextPDF\CodeIgniter\ 對映到 src/CodeIgniter/。透過這層對映，framework 會把 NextPDF\CodeIgniter\Config\Services resolve（解析）到對應檔案（PSR-4 §x1.x3）。/integrations/codeigniter/boot-and-discovery/ 一節記錄完整流程，以及控制探索行為的 Config\Modules 屬性。

容器繫結

CodeIgniter 4 並未內建 PSR-11 容器。PSR-11 §1.3 不鼓勵採用 service-locator 模式（規範性 SHOULD NOT）。此套件遵循 framework 的 locator 慣例，但維持最精簡的形式。每個繫結都是具名靜態工廠（factory），並帶有一個 bool $getShared 參數。

服務名稱	回傳	預設生命週期
`fontRegistry`	`FontRegistryInterface`	共用
`imageRegistry`	`ImageRegistry`	共用
`documentFactory`	`DocumentFactoryInterface`	共用
`pdfDocument`	`Document`	全新
`pdf`	`Pdf`	全新
`tsaClient`	`?TsaClient`	共用
`pdfSigner`	`?SignerInterface`	全新

下列兩個進入點都可解析，且彼此等效：

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Config\Services;

$a = Services::pdf(false);   // direct
$b = \service('pdf');        // helper → Services::pdf()

全域的 pdf() 與 pdf_document() helper 只是 Services::pdf(false) 與 Services::pdfDocument(false) 的輕量包裝。

發布組態

套件組態位於 NextPDF\CodeIgniter\Config\NextPdf，這是一個非 final 的 BaseConfig。你可以使用以下兩種受支援的覆寫方式：

1. 繼承該類別（具型別，並納入版本控管）。建立 app/Config/NextPdf.php：

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

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

CodeIgniter 會載入你的應用程式類別，並取代套件預設值。

2. 以 .env 覆寫（依環境設定）。前綴為小寫短類別名稱 nextpdf：

nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem

/integrations/codeigniter/configuration/ 一節記錄每個鍵與陣列覆寫規則。

Service-provider/bundle 冒煙測試

CodeIgniter 沒有可供測試的 service provider 或 bundle 類別。因此，等效的冒煙測試會檢查兩件事：探索是否能解析出這些服務，以及生命週期行為是否符合規格。下方測試是一個可實際執行的控制器（controller）動作，對應套件自身的功能性斷言。

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\ResponseInterface;
use NextPDF\CodeIgniter\Config\Services;
use NextPDF\CodeIgniter\Libraries\Pdf;
use NextPDF\Core\Document;

final class NextPdfSmokeController extends BaseController
{
    public function check(): ResponseInterface
    {
        // Discovery resolved the services.
        $document = Services::pdfDocument(false);
        $library = Services::pdf(false);

        // Documents are fresh per call (no cross-request leakage).
        $freshIsolated = Services::pdfDocument(false) !== $document;

        // Registries are shared singletons.
        $registrySingleton = Services::fontRegistry() === Services::fontRegistry();

        // Optional services degrade to null without Premium / TSA config.
        $signerOptional = Services::pdfSigner(false) === null;

        $ok = $document instanceof Document
            && $library instanceof Pdf
            && $freshIsolated
            && $registrySingleton
            && $signerOptional;

        return $this->response
            ->setStatusCode($ok ? 200 : 500)
            ->setJSON([
                'discovery' => $document instanceof Document,
                'document_fresh_per_call' => $freshIsolated,
                'registry_shared' => $registrySingleton,
                'signer_optional_null' => $signerOptional,
            ]);
    }
}

將一條路由對映到這個動作後發出請求。若收到 200 回應，且所有旗標都為 true，即可證明整合成立。這裡的每一條斷言，都對應到套件功能測試套件中一項已驗證的行為。

邊界案例與注意事項

若宿主應用程式關閉 Composer 探索，請把 nextpdf/codeigniter 加入 Config\Modules::$composerPackages['only']。
Services::pdfDocument(true) 會回傳共用的 document。它僅供測試重設使用。切勿在請求或 job 程式碼中取得共用 document。
Services::pdfSigner() 與 Services::tsaClient() 都會回傳 null；在設定簽章或 TSA URL 之前皆是如此。這是刻意設計的優雅降級，並非失敗。

符合性

用於模組探索的類別路徑對映（PSR-4 Autoloader §x1.x3）。
繫結模型所依循的 service-locator 指引（PSR-11 Container §1.3）。

商業脈絡

NextPDF 核心採 Apache-2.0 授權。Pro 與 Enterprise 服務一旦安裝，就會出現在同一個 Services 介面上。CodeIgniter 套件會公開對應的服務方法。在對應的 Premium 套件安裝之前，每個方法都會回傳 null。請見 </get-license/?intent=codeigniter>。

另見

/integrations/codeigniter/boot-and-discovery/ — 探索內部機制。
/integrations/codeigniter/install/ — 版本限制與驗證。
/integrations/codeigniter/quickstart/ — 第一份 PDF。
/integrations/codeigniter/production-usage/ — DI 接線的控制器與佇列 job。
/integrations/codeigniter/configuration/ — 每一個組態鍵。