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 约定，同时保持实现尽可能精简。每个绑定都是带有 bool $getShared 参数的具名静态工厂（factory）。

服务名称	返回	默认生命周期
`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。
在配置签名或 TSA URL 之前，Services::pdfSigner() 与 Services::tsaClient() 都会返回 null。这是有意设计的优雅降级，并非失败。

符合性

用于模块探索的类路径映射（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/ — 每个配置键。