CodeIgniter 4 向け NextPDF の構成

概要

構成は NextPDF\CodeIgniter\Config\NextPdf（CodeIgniter の BaseConfig サブクラス）にあります。値を上書きするには、app/Config/ でクラスを拡張するか、nextpdf. プレフィックスを付けた .env キーを設定します。デフォルト値だけで、追加の構成なしでも動作します。

概念の概要

NextPdf は型付きの BaseConfig です。これは意図的に final ではありません。CodeIgniter では、アプリケーション側の構成がパッケージクラスを拡張するのが慣例であり、これによりアプリケーションはデフォルト値を上書きできます。CodeIgniter が構成を組み立てる際、BaseConfig はすべての public プロパティについて、環境による上書きを解決（resolve）します。この解決には、ネストされた配列キーも含まれます。

デフォルトのフォントパスとキャッシュパスは、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 の creator メタデータ。
defaults.author	string	''	author メタデータ。空の場合はスキップ。
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	設定時のトリムボックス。
defaults.bleed_box	list<float>|null	null	設定時のブリードボックス。

パッケージは 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	ウォームアップ後のフォントキャッシュロック。

フォントレジストリは、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 プロファイルのパス。

pdfa は、NextPDF Pro がインストールされ、 アーカイブ機能が利用可能な場合にのみ有効になります。コアのみの環境では、このキーは無視されます。

デジタル署名（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() は、signature.enabled が true で、かつ signature.certificate が空でない場合を除き、null を返します。デフォルトのレベルは B-B です。NextPDF Pro は B-B ベースライン署名を提供します。長期検証レベルは、別個の Enterprise 機能です。それらはここではなく、Premium リファレンスに記載されています。

PAdES B-T は Core エンジンによって生成されます。CodeIgniter 統合自体が B-T を追加することはなく、Pro が提供するのは B-B ベースラインのみです。このドキュメントは、Pro B-T が提供される場合に更新されます。

タイムスタンプ局

キー	型	デフォルト	説明
tsa.url	string|null	null	TSA エンドポイントの URL。
tsa.username	string	''	TSA の Basic 認証ユーザー名。
tsa.password	string	''	TSA の Basic 認証パスワード。
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	TSA への平文 HTTP の許可。

Services::tsaClient() は、tsa.url が null または空文字列の場合に null を返します。タイムスタンプを必要とする署名レベルが選択された場合、 署名処理側は自動的に TSA クライアントを接続します。

OCSP キャッシュ

キー	型	デフォルト	説明
ocspCache.enabled	bool	true	OCSP レスポンスキャッシュの有効化。
ocspCache.ttl	int	86400	キャッシュの TTL（秒単位）。
ocspCache.directory	string|null	null	キャッシュディレクトリ。null の場合はエンジンのデフォルト。

Chrome HTML レンダラー（NextPDF Artisan）

キー	型	デフォルト	説明
artisan.chrome_binary	string|null	null	Chrome/Chromium バイナリのパス。
artisan.render_timeout	int	30	レンダリングのタイムアウト（秒）。
artisan.default_css	string	''	デフォルトのスタイルシート。
artisan.no_sandbox	bool	false	Chrome に渡す --no-sandbox。
artisan.max_html_size	int	5000000	入力 HTML の最大サイズ（バイト）。

ドキュメントに対して Chrome レンダラーが構成されるのは、 artisan.chrome_binary が設定され、かつ nextpdf/artisan がインストールされている場合のみです。

.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/. を参照してください。

準拠

• アプリケーションの構成拡張ファイルは、1 つのクラスを宣言し、副作用はありません（PSR-1 §x1.x1.p3）。

商用に関する背景

NextPDF コアは Apache-2.0 です。signature.* および pdfa キーは、NextPDF Pro または Enterprise がインストールされている場合にのみ有効になります。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/ — 署名とパス構成の堅牢化。