在 CodeIgniter 4 中配置 NextPDF

快速总览

配置存放在 NextPDF\CodeIgniter\Config\NextPdf，这是 CodeIgniter 的 BaseConfig 子类。你可以在 app/Config/ 中扩展这个类来覆盖值，或设置带有 nextpdf. 前缀的 .env 键。无需任何配置时，默认值即可正常工作。

概念总览

NextPdf 是一个带类型声明的 BaseConfig。它有意设计为 非 final。CodeIgniter 的惯例是让应用配置扩展软件包类，这样应用就能覆盖默认值。当 CodeIgniter 构建配置时，BaseConfig 会为每个 public 属性解析环境覆盖值。这个解析过程也涵盖嵌套数组键。

默认字体和缓存路径使用 CodeIgniter 的 WRITEPATH 常量：WRITEPATH . 'fonts' 与 WRITEPATH . 'cache/nextpdf'。

配置键

下列每个键都是 NextPdf 的一个 public 属性。默认值均已根据软件包源代码核验。

页面与文档默认值

项目	类型	默认值	说明
pageFormat	string	A4	页面格式。
orientation	string	P	P 表示纵向，L 表示横向。
unit	string	mm	计量单位。
defaults.creator	string	NextPDF	PDF 创建者元数据。
defaults.author	string	''	作者元数据；为空时跳过。
defaults.language	string	en	文档语言标签。
defaults.margin_top	float	10.0	上边距。
defaults.margin_right	float	10.0	右边距。
defaults.margin_bottom	float	10.0	下边距。
defaults.margin_left	float	10.0	左边距。
defaults.font_family	string	dejavusans	默认字体系列。
defaults.font_size	float	12.0	默认字号。
defaults.trim_box	list<float>|null	null	设置后作为裁切框（trim box）。
defaults.bleed_box	list<float>|null	null	设置后作为出血框（bleed box）。

软件包会把 defaults.creator 与 defaults.language 应用于每一份文档。只有在 defaults.author 的值非空时才会应用。

路径与缓存

项目	类型	默认值	说明
fontsPath	string	WRITEPATH/fonts	字体文件目录。
cachePath	string	WRITEPATH/cache/nextpdf	缓存目录。
preloadFonts	list<string>	[]	启动时预热的绝对字体路径。
imageCacheMb	int	50	图像 LRU 缓存预算，以 MB 为单位。
fontCacheLocking	bool	true	预热后锁定字体缓存。

字体注册表会拒绝包含 stream wrapper（://）或 null byte 的 fontsPath。这种拒绝会引发运行时错误。 详见 /integrations/codeigniter/security-and-operations/.

归档与色彩（NextPDF Pro）

项目	类型	默认值	说明
pdfa	string|null	null	PDF/A 版本：4、4e、4f。
iccProfile.rgb	string|null	null	RGB ICC 配置文件路径。
iccProfile.cmyk	string|null	null	CMYK ICC 配置文件路径。

只有在安装 NextPDF Pro 且归档能力可用时，pdfa 才会生效， 此时才视为归档能力就绪。仅有 core 时，这个键会被忽略。

数字签名（NextPDF Pro / Enterprise）

项目	类型	默认值	说明
signature.enabled	bool	false	启用签名服务。
signature.certificate	string|null	null	证书文件路径。
signature.private_key	string|null	null	私钥文件路径。
signature.password	string	''	私钥密码。
signature.extra_certs	list<string>	[]	额外链证书路径。
signature.level	string	B-B	签名级别标识符。

Services::pdfSigner() 会返回 null，除非 signature.enabled 为 true，且 signature.certificate 非空。默认等级是 B-B。NextPDF Pro 提供 B-B 基线签名。长期验证等级是另一项 Enterprise 能力。相关内容记录在 Premium 参考文档中，此处不展开。

PAdES B-T 由 Core 引擎生成。CodeIgniter 集成本身不会添加 B-T，且 Pro 仅提供 B-B 基线能力。本文档会在 Pro B-T 推出时（若有）同步更新。

时间戳认证机构（TSA）

项目	类型	默认值	说明
tsa.url	string|null	null	TSA 端点 URL。
tsa.username	string	''	TSA 基本认证用户名。
tsa.password	string	''	TSA 基本认证密码。
tsa.cert	string|null	null	客户端证书路径。
tsa.key	string|null	null	客户端密钥路径。
tsa.timeout	int	30	请求超时秒数。
tsa.pinned_public_keys	list<string>	[]	已固定的 TSA 公钥。
tsa.warn_on_key_rotation	bool	true	TSA 密钥轮换时发出警告。
tsa.allow_insecure_http	bool	false	允许通过明文 HTTP 连接到 TSA。

Services::tsaClient() 会返回 null，条件是 tsa.url 为 null 或空字符串。选择需要时间戳的签名级别时， 签名器会自动接入 TSA 客户端。

OCSP 缓存

项目	类型	默认值	说明
ocspCache.enabled	bool	true	启用 OCSP 响应缓存。
ocspCache.ttl	int	86400	缓存生存时间（TTL），以秒为单位。
ocspCache.directory	string|null	null	缓存目录；为 null 时使用引擎默认值。

Chrome HTML renderer（渲染器）（NextPDF Artisan）

项目	类型	默认值	说明
artisan.chrome_binary	string|null	null	Chrome / Chromium 二进制文件路径。
artisan.render_timeout	int	30	渲染超时秒数。
artisan.default_css	string	''	默认样式表。
artisan.no_sandbox	bool	false	将 --no-sandbox 传给 Chrome。
artisan.max_html_size	int	5000000	输入 HTML 的大小上限，以字节为单位。

只有在设置了 artisan.chrome_binary 且 安装了 nextpdf/artisan 时，才会为文档设置 Chrome renderer。

使用 .env 覆盖设置

BaseConfig 会逐个属性解析环境覆盖值。查找键使用小写的短类名 nextpdf，后接属性路径。嵌套数组键使用点号寻址。点号与下划线两种形式都可接受。

.env

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

前缀是小写的短类名。即使类名写成 NextPdf，前缀仍保持 nextpdf。完全限定形式（NextPDF\CodeIgniter\Config\NextPdf.fontsPath）也可接受。

以扩展类的方式覆盖

若要使用带类型声明、纳入版本控制的配置，请在 app/Config/ 中扩展软件包类。CodeIgniter 会加载应用类，取代软件包默认值。这个文件只声明一个类，不产生任何副作用。这样符合 PSR-1 的期望：一个文件要么声明符号，要么执行有副作用的逻辑，但两者不可兼有（PSR-1 §x1.x1.p3）。

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

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

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

边界情况与陷阱

• 使用 .env 覆盖单个嵌套键时，只会覆盖该键；数组的其余部分保持默认值。
• .env 的值都是字符串。CodeIgniter 会转换 true / false 与数字字符串。需要保持为字面字符串的值，请加上引号。
• 扩展类时，如果只提供部分 defaults 数组，会替换整个数组。请纳入每一个键，如上所示。

安全注意事项

请勿将证书与密钥路径纳入源代码版本控制。请通过 .env 或机密管理工具提供它们。在生产环境中，tsa.allow_insecure_http 必须保持 false。详见 /integrations/codeigniter/security-and-operations/.

合规性

• 应用配置扩展文件只声明一个类，且没有副作用（PSR-1 §x1.x1.p3）。

商业背景

NextPDF core 采用 Apache-2.0 许可。只有在安装 NextPDF Pro 或 Enterprise 时，signature.* 与 pdfa 键才会生效。CodeIgniter 软件包会公开对应的服务方法。在安装对应的 Premium 软件包之前，这些方法都会返回 null。详见 </get-license/?intent=codeigniter-signing>。

另请参阅

• /integrations/codeigniter/install/ — 安装软件包。
• /integrations/codeigniter/quickstart/ — 第一份 PDF。
• /integrations/codeigniter/production-usage/ — 使用 DI 装配的控制器与队列任务。
• /integrations/codeigniter/security-and-operations/ — 强化签名与路径配置。