Configure NextPDF for CodeIgniter 4

At a glance

NextPDF configuration lives in NextPDF\CodeIgniter\Config\NextPdf, a CodeIgniter BaseConfig subclass. You can override values by extending the class in app/Config/ or by setting .env keys with the nextpdf. prefix. Defaults work without extra configuration.

Conceptual overview

NextPdf is a typed BaseConfig. It is intentionally not final. In CodeIgniter, application configuration extends the package class so your app can override defaults. When CodeIgniter constructs the config, BaseConfig resolves environment overrides for every public property, including nested array keys.

The default font and cache paths use CodeIgniter’s WRITEPATH constant: WRITEPATH . 'fonts' and WRITEPATH . 'cache/nextpdf'.

Configuration keys

Each key below is a public property of NextPdf. Defaults are verified against the package source.

Page and document defaults

Key	Type	Default	Description
`pageFormat`	`string`	`A4`	Page format.
`orientation`	`string`	`P`	`P` portrait or `L` landscape.
`unit`	`string`	`mm`	Measurement unit.
`defaults.creator`	`string`	`NextPDF`	Portable Document Format (PDF) creator metadata.
`defaults.author`	`string`	`''`	Author metadata; skipped when empty.
`defaults.language`	`string`	`en`	Document language tag.
`defaults.margin_top`	`float`	`10.0`	Top margin.
`defaults.margin_right`	`float`	`10.0`	Right margin.
`defaults.margin_bottom`	`float`	`10.0`	Bottom margin.
`defaults.margin_left`	`float`	`10.0`	Left margin.
`defaults.font_family`	`string`	`dejavusans`	Default font family.
`defaults.font_size`	`float`	`12.0`	Default font size.
`defaults.trim_box`	`list<float>\|null`	`null`	Trim box, when set.
`defaults.bleed_box`	`list<float>\|null`	`null`	Bleed box, when set.

The package applies defaults.creator and defaults.language to every document. It applies defaults.author only when the value is non-empty.

Paths and caches

Key	Type	Default	Description
`fontsPath`	`string`	`WRITEPATH/fonts`	Font file directory.
`cachePath`	`string`	`WRITEPATH/cache/nextpdf`	Cache directory.
`preloadFonts`	`list<string>`	`[]`	Absolute font paths warmed at boot.
`imageCacheMb`	`int`	`50`	Image least recently used (LRU) cache budget in megabytes (MB).
`fontCacheLocking`	`bool`	`true`	Lock the font cache after warmup.

The font registry rejects any fontsPath that contains a stream wrapper (://) or a null byte, and raises a runtime error. See /integrations/codeigniter/security-and-operations/.

Archiving and color (NextPDF Pro)

Key	Type	Default	Description
`pdfa`	`string\|null`	`null`	PDF/A version: `4`, `4e`, `4f`.
`iccProfile.rgb`	`string\|null`	`null`	Red, green, and blue (RGB) International Color Consortium (ICC) profile path.
`iccProfile.cmyk`	`string\|null`	`null`	Cyan, magenta, yellow, and key (CMYK) ICC profile path.

pdfa takes effect only when NextPDF Pro is installed and the archiving capability is available. In core alone, the key is ignored.

Digital signature (NextPDF Pro / Enterprise)

Key	Type	Default	Description
`signature.enabled`	`bool`	`false`	Enable the signer service.
`signature.certificate`	`string\|null`	`null`	Certificate file path.
`signature.private_key`	`string\|null`	`null`	Private key file path.
`signature.password`	`string`	`''`	Private key password.
`signature.extra_certs`	`list<string>`	`[]`	Additional chain certificate paths.
`signature.level`	`string`	`B-B`	Signature level identifier.

Services::pdfSigner() returns null unless signature.enabled is true and signature.certificate is non-empty. The default level is B-B. NextPDF Pro provides the B-B baseline signature. Long-term validation levels are a separate Enterprise capability and are documented in the Premium reference, not here.

PDF Advanced Electronic Signatures (PAdES) B-T is produced by the Core engine. The CodeIgniter integration does not itself add B-T, and Pro delivers the B-B baseline only. This documentation will be updated if and when Pro B-T ships.

Time Stamp Authority

Key	Type	Default	Description
`tsa.url`	`string\|null`	`null`	Time Stamp Authority (TSA) endpoint URL.
`tsa.username`	`string`	`''`	TSA basic authentication username.
`tsa.password`	`string`	`''`	TSA basic authentication password.
`tsa.cert`	`string\|null`	`null`	Client certificate path.
`tsa.key`	`string\|null`	`null`	Client key path.
`tsa.timeout`	`int`	`30`	Request timeout in seconds.
`tsa.pinned_public_keys`	`list<string>`	`[]`	Pinned TSA public keys.
`tsa.warn_on_key_rotation`	`bool`	`true`	Warn on TSA key rotation.
`tsa.allow_insecure_http`	`bool`	`false`	Permit plaintext HTTP to the TSA.

Services::tsaClient() returns null when tsa.url is null or an empty string. When you select a signature level that requires a timestamp, the signer attaches the TSA client automatically.

OCSP cache

Key	Type	Default	Description
`ocspCache.enabled`	`bool`	`true`	Enable the Online Certificate Status Protocol (OCSP) response cache.
`ocspCache.ttl`	`int`	`86400`	Cache time to live (TTL) in seconds.
`ocspCache.directory`	`string\|null`	`null`	Cache directory; engine default when null.

Chrome HTML renderer (NextPDF Artisan)

Key	Type	Default	Description
`artisan.chrome_binary`	`string\|null`	`null`	Chrome/Chromium binary path.
`artisan.render_timeout`	`int`	`30`	Render timeout in seconds.
`artisan.default_css`	`string`	`''`	Default stylesheet.
`artisan.no_sandbox`	`bool`	`false`	Pass `--no-sandbox` to Chrome.
`artisan.max_html_size`	`int`	`5000000`	Maximum input HTML size in bytes.

The Chrome renderer is configured for the document only when artisan.chrome_binary is set and nextpdf/artisan is installed.

Override with `.env`

BaseConfig resolves environment overrides per property. The lookup key is the lowercase short class name, nextpdf, followed by the property path. Use dots to address nested array keys. Both dotted and underscore forms are accepted.

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

The prefix is the lowercase short class name. It stays nextpdf even though the class is written NextPdf. You can also use the fully qualified form (NextPDF\CodeIgniter\Config\NextPdf.fontsPath).

Override by extending the class

For typed, version-controlled configuration, extend the package class in app/Config/. CodeIgniter loads the application class instead of the package default. This file declares a class and causes no side effects. That keeps it aligned with the PSR-1 expectation that a file either declares symbols or runs side-effecting logic, but not both (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,
    ];
}

Edge cases & gotchas

Overriding a single nested key with .env changes that key only; the rest of the array keeps its default.
.env values are strings. CodeIgniter casts true/false and numeric strings. Quote values that must stay literal strings.
Extending the class with a partial defaults array replaces the whole array. Include every key, as shown above.

Security notes

Keep certificate and key paths out of source control. Supply them through .env or a secrets manager. tsa.allow_insecure_http must stay false in production. See /integrations/codeigniter/security-and-operations/.

Conformance

The application config-extension file declares one class and no side effects (PSR-1 §x1.x1.p3).

Commercial context

NextPDF core is Apache-2.0. The signature.* and pdfa keys take effect only when NextPDF Pro or Enterprise is installed. The CodeIgniter package exposes the corresponding service methods. Those methods return null until you install the matching Premium package. See </get-license/?intent=codeigniter-signing>.