CodeIgniter API 参考

概览

CodeIgniter 包对外暴露了一组精简、面向控制器（controller）的接口：用于包装单个文件的 Pdf 库包装器（搭配 Services::pdf() 和全局 pdf() 辅助函数使用）、将已构建文件转换为 DownloadResponse 的响应辅助函数（PdfResponse）、背后的 Services 工厂（字体/图像注册表、文件工厂、可选的签章器和 TSA 客户端）、NextPdf 配置类，以及用于通过静态构建器可调用项异步生成文件的 GeneratePdfJob。

建议从这里开始：在控制器中调用 Services::pdf()（或 pdf() 辅助函数），用 $pdf->document() 添加内容，再返回 $pdf->download('file.pdf')。这条路径已经涵盖最常见的任务。下方的参考表格按接口分类整理；「常见任务」一节会先示范可直接执行的代码模板。

常见任务

以下是最常用的实际流程。每个示例都已对照 nextpdf/codeigniter 源码验证过。

从控制器返回可下载的 PDF，是标准的绘制路径：

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, "Invoice #{$id}");

        return $pdf->download("invoice-{$id}.pdf");
    }
}

它的作用：resolve（解析）得到一个全新的 Pdf，包装一个全新的 Document，写入一个单元格，并返回一个带有 attachment 处置方式和包级安全标头的 DownloadResponse。

在浏览器中内嵌预览 PDF 时，使用同一个包装器，改用 inline() 而非 download()：

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;

final class ReportController extends BaseController
{
    public function preview(): DownloadResponse
    {
        $pdf = pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly Report');

        return $pdf->inline('report.pdf');
    }
}

它的作用：使用全局 pdf() 辅助函数（等同于 Services::pdf()），并返回一个带有 inline 处置方式的 DownloadResponse，让浏览器直接显示 PDF，而不是下载。

要在队列中异步生成 PDF，请将带有静态构建器的 GeneratePdfJob 推入队列：

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

service('queue')->push('pdf', GeneratePdfJob::class, [
    'builder'    => 'App\PdfBuilders\InvoiceBuilder::build',
    'outputPath' => WRITEPATH . 'pdfs/invoice-42.pdf',
    'context'    => ['invoice_id' => 42],
]);

它的作用：将生成作业排入队列。worker 会验证构建器（必须是 App\PdfBuilders\...::method 形式的静态可调用项）和输出路径（必须解析到 WRITEPATH/pdfs/ 下并以 .pdf 结尾），构建一个全新文件，然后将其保存。

库包装器

当你持有一个 Pdf 包装器、需要其响应或保存方法时，请参考这张表格。

符号	参数	默认行为	返回	抛出或失败条件	备注
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`：全新的核心文件。	包装所提供的文件，供单次响应或保存作业使用。	`Pdf`	预期不会发生。	输出之后请勿重复使用该包装器。
`Pdf::document()`	无。	返回被包装的文件。	`NextPDF\Core\Document`	预期不会发生。	用它来调用核心的编写 API。
`Pdf::inline(string $filename = 'document.pdf')`	`filename`：响应文件名。	浏览器内嵌（inline）处置方式。	`CodeIgniter\HTTP\DownloadResponse`	核心序列化错误。	委派给 `PdfResponse::inline()`。
`Pdf::download(string $filename = 'document.pdf')`	`filename`：响应文件名。	浏览器附件（attachment）处置方式。	`DownloadResponse`	核心序列化错误。	委派给 `PdfResponse::download()`。
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`：响应文件名。	与其他 Framework（框架）包保持 API 一致。	`DownloadResponse`	核心序列化错误。	CodeIgniter 原生即可处理二进制输出。
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`：响应文件名。	与其他框架包保持 API 一致。	`DownloadResponse`	核心序列化错误。	使用与非流式响应相同的大小控制选项。
`Pdf::save(string $path)`	`path`：文件系统的目标路径。	写出被包装的文件。	`void`	文件系统或核心写入错误。	保存前请先验证存储根目录。

服务与辅助函数

当你需要特定的服务工厂或某个全局辅助函数，并想了解其共享行为和返回类型时，请参考这张表格。

符号	参数	默认行为	返回	抛出或失败条件	备注
`Services::fontRegistry(bool $getShared = true)`	`getShared`：CodeIgniter 共享服务标志。	共享的注册表，会以已配置的字体预热，然后锁定。	`FontRegistryInterface`	`RuntimeException`：缺少扩展或字体路径不安全时。	拒绝 `fontsPath` 中的流包装器和空字节。
`Services::imageRegistry(bool $getShared = true)`	`getShared`：共享服务标志。	共享且有界的 LRU 图像注册表。	`ImageRegistry`	预期不会发生。	缓存大小由 `imageCacheMb` 控制。
`Services::documentFactory(bool $getShared = true)`	`getShared`：共享服务标志。	使用共享注册表的共享工厂。	`DocumentFactoryInterface`	注册表配置错误。	工厂可以重复使用；文件不可以。
`Services::tsaClient(bool $getShared = true)`	`getShared`：共享服务标志。	返回 `null`（当 `tsa.url` 为空时）。	客户端 `TsaClient	null`	HTTP 客户端或 TSA 配置错误。
`Services::pdfSigner(bool $getShared = false)`	`getShared`：共享服务标志。	当签章功能禁用时返回 `null`。	签章器接口 `SignerInterface	null`	证书或签章层级的错误。
`Services::pdfDocument(bool $getShared = false)`	`getShared`：共享服务标志。	创建一个全新文件、应用默认值，并可选地设置 PDF/A 或 Artisan。	`Document`	可选扩展或文件配置错误。	为保证请求安全，请保留默认值 `false`。
`Services::pdf(bool $getShared = false)`	`getShared`：共享服务标志。	创建一个全新的 `Pdf` 包装器，包装一个全新文件。	`NextPDF\CodeIgniter\Libraries\Pdf`	文件配置错误。	主要的面向控制器服务。
`Services::eInvoiceEmbedder()`	无。	除非存在 Premium Pro 电子发票嵌入器类，否则返回 `null`。	嵌入器接口 `EmbedderInterface	null`	可选包的构建错误。
`Services::eInvoiceValidator()`	无。	除非存在 Premium Enterprise 验证器类，否则返回 `null`。	验证器接口 `ValidatorInterface	null`	可选包的构建错误。
`Services::eInvoiceProfile()`	无。	当已安装 Premium Pro 时返回 EN16931 配置文件。	配置文件接口 `ProfileInterface	null`	可选包的错误。
`Services::schematronRunner()`	无。	除非存在 Premium Enterprise 的 Schematron 验证器，否则返回 `null`。	执行器接口 `SchematronRunnerInterface	null`	可选包的构建错误。
`Registrar::Autoload()`	无。	将包辅助函数加入 CodeIgniter 的 autoload 配置。	`array`	预期不会发生。	在模块加载后启用 `pdf()` 与 `pdf_document()`。
`pdf()`	无。	调用 `Services::pdf(false)`。	`Pdf`	文件配置错误。	供控制器使用的便利辅助函数。
`pdf_document()`	无。	调用 `Services::pdfDocument(false)`。	`Document`	文件配置错误。	偏好直接使用核心文件 API 时的便利辅助函数。

HTTP 响应

当你已经持有一个已构建的 Document，并想绕过 Pdf 包装器自行构建 DownloadResponse 时，请参考这张表格。

符号	参数	默认行为	返回	抛出或失败条件	备注
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`：已构建的文件；`filename`：响应文件名。	确保具有 `.pdf` 扩展名和内嵌处置方式。	`DownloadResponse`	核心序列化错误。	加入 PDF 内容类型和防御性标头。
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	与 `inline` 相同；处置方式为 attachment。	确保具有 `.pdf` 扩展名。	`DownloadResponse`	与 `inline` 相同。	用于浏览器下载。
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	与 `inline` 相同。	在 CI4 中与 `inline` 行为相同。	`DownloadResponse`	与 `inline` 相同。	用于保持跨框架 API 一致性。
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	与 `download` 相同。	在 CI4 中与 `download` 行为相同。	`DownloadResponse`	与 `download` 相同。	用于保持跨框架 API 一致性。

队列作业

当你接入异步生成，并需要精确了解作业数据键和构建器可调用项的契约时，请参考这张表格。

符号	参数	默认行为	返回	抛出或失败条件	备注
`GeneratePdfJob::process()`	作业数据键：`builder`、`outputPath`，以及可选的 `context`。	省略时使用空的 context 数组。	`void`	`InvalidArgumentException`：构建器或输出路径不安全时；以及核心写入错误。	构建器必须是 `App\PdfBuilders\...\*::method`。
构建器可调用项	`Document $doc`、`array $context`。	除了作业数据外没有默认的 context。	`Document`	构建器特定的异常。	必须是静态可调用项，因为 CI4 队列载荷是序列化后的数据。

配置

当你要在 NextPdf 配置类上变更默认值（页面格式、路径、签章、TSA 或文件元数据）时，请参考这张表格。

属性	类型	默认行为	备注
`pageFormat`	`string`	`A4`。	默认页面格式。
`orientation`	`string`	`P`。	默认方向。
`unit`	`string`	`mm`。	默认单位。
`pdfa`	`string	null`	`null`。
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` 与 `WRITEPATH . 'cache/nextpdf'`。	请将路径保留在应用程序可控的存储范围内。
`signature`	`array`	以级别 `B-B` 禁用。	证书、密钥、密码、额外证书和级别。
`tsa`	`array`	当 URL 为 `null` 时禁用；超时为 30 秒。	证书信息、mTLS 文件、公钥钉扎和 HTTP 策略。
`ocspCache`	`array`	已启用，TTL 为 86400 秒。	可用时供签章验证流程使用。
`preloadFonts`	`list<string>`	空。	在注册表锁定之前预热。
`imageCacheMb`	`int`	`50`。	控制进程生命周期内的图像缓存。
`fontCacheLocking`	`bool`	`true`。	让字体注册表的变更不会影响请求处理。
`artisan`	`array`	除非已配置并安装，否则 Chrome renderer（渲染器）处于禁用状态。	映射到 `ChromeRendererConfig::fromArray()`。
`defaults`	`array`	创建者为 `NextPDF`，作者留空，语言为 `en`，并使用默认边距和字体。	`Services::pdfDocument()` 只应用 `creator`、`language`，以及（非空时的）`author`；而 `margin_top`/`right`/`bottom`/`left`、`font_family`、`font_size`、`trim_box` 与 `bleed_box` 等键已定义，但目前尚未作为默认值应用。

开发备注

GeneratePdfJob 将输出限制在 WRITEPATH . 'pdfs'，且要求以 .pdf 结尾。
位于 App\PdfBuilders 之外的构建器可调用项会被拒绝，以避免从被篡改的队列载荷执行任意代码。
控制器流程请使用 service('pdf') 或包辅助函数；长时间执行的生成作业请使用队列作业。