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/ — 发现失败模式。