NextPDF Laravel パッケージの構成

概要

config/nextpdf.php は php artisan vendor:publish --tag=nextpdf-config で公開されます。各キーには、環境変数によるフォールバックとハードコードされたデフォルト値があります。このページでは、パッケージの config/nextpdf.php に記述されているとおりに各キーを説明します。

インストール

php artisan vendor:publish --tag=nextpdf-config

プロバイダーは register() の実行中に、nextpdf 構成キー配下へパッケージのデフォルト値をマージします。したがって、未設定のキーは、公開前であっても以下の値にフォールバックします。

概念の概要

ほとんどの環境変数は、NEXTPDF_* という名前か、レガシーの TCPDF_* という名前のいずれかを受け付けます。レガシーのプレフィックスは UPGRADE.md に記載された移行期間中はサポートされますが、新規デプロイでは NEXTPDF_* 形式を使用してください。構成ファイルは、環境変数 → 公開ファイルの値 → パッケージのデフォルト値の順に値を resolve（解決）します。

API サーフェス — 構成キー

ドキュメントのレイアウト

キー	環境変数（主）	デフォルト	効果
`page_format`	`NEXTPDF_PAGE_FORMAT`	`A4`	デフォルトのページ形式（A4、A3、A5、Letter、Legal、Tabloid）
`orientation`	`NEXTPDF_ORIENTATION`	`P`	縦向き（`P`）または横向き（`L`）
`unit`	`NEXTPDF_UNIT`	`mm`	測定単位（pt、mm、cm、in）
`defaults.creator`	`NEXTPDF_CREATOR`	`NextPDF`	ドキュメント作成者のメタデータ。`PdfDocumentInterface` バインディングへの適用
`defaults.author`	`NEXTPDF_AUTHOR`	（空）	作成者のメタデータ。空でない場合のみ適用
`defaults.language`	`NEXTPDF_LANG`	`en`	ドキュメントの言語。ドキュメントバインディングへの適用
`defaults.margin_top` / `_right` / `_bottom` / `_left`	—	`10`	デフォルトの余白
`defaults.font_family`	—	`dejavusans`	デフォルトのフォントファミリー
`defaults.font_size`	—	`12`	デフォルトのフォントサイズ
`defaults.trim_box`	—	`null`	ポイント単位の TrimBox `[left, bottom, right, top]`、または `null`
`defaults.bleed_box`	—	`null`	ポイント単位の BleedBox `[left, bottom, right, top]`、または `null`

プロバイダーは、defaults.creator、defaults.language、および（設定されている場合は）defaults.author を、新しく解決されたすべてのドキュメントに適用します。defaults.author の分岐は、値が空の場合にスキップされます。

アーカイブとカラー

キー	環境変数（主）	デフォルト	効果
`pdfa`	`NEXTPDF_PDFA`	`null`	PDF/A のアーカイブレベル（`null`、`4`、`4e`、`4f`）。null 以外を指定するとドキュメントバインディングで PDF/A が有効になり、追加要件として `nextpdf/premium` が必要
`fonts_path`	`NEXTPDF_FONTS_PATH`	`resource_path('fonts')`	追加の TrueType フォント用ディレクトリ。フォントレジストリの検索パスを駆動
`cache_path`	`NEXTPDF_CACHE_PATH`	`storage_path('framework/cache/tcpdf')`	解析済みフォントと一時ファイルのキャッシュディレクトリ
`icc_profile.rgb`	`NEXTPDF_ICC_PROFILE_RGB`	`null`	RGB ICC プロファイルのパス。PDF/A に必要
`icc_profile.cmyk`	`NEXTPDF_ICC_PROFILE_CMYK`	`null`	印刷ワークフロー用のオプションの CMYK ICC プロファイル
`font_cache_locking`	`NEXTPDF_FONT_CACHE_LOCKING`	`true`	並行するキューワーカーの書き込み時に破損を防ぐため、フォントキャッシュに `flock` を使用

pdfa に null 以外の値を設定するには Premium 階層が必要です。nextpdf/premium がない状態で pdfa を設定してドキュメントバインディングを解決すると、PDF/A バージョン型に対して class-not-found エラーが発生します。このページでは Premium のアーカイブ動作については説明しません。Premium のドキュメントを参照してください。

ワーカーメモリ（長寿命ランタイム）

キー	環境変数（主）	デフォルト	効果
`preload_fonts`	—	`[]`	ワーカー起動時に解析されるフォントファイル絶対パスのリスト。ウォームアップ後、フォントレジストリはロック
`image_cache_mb`	`NEXTPDF_IMAGE_CACHE_MB`	`50`	MB 単位の LRU イメージキャッシュ予算。`0` はキャッシュを無効化。プロバイダーレベルで強制される上限なし

イメージキャッシュ予算には、プロバイダー側で強制される上限はありません。コンテナのメモリ制限または php.inimemory_limit を適用して、上限を設けてください。構成ファイルでは、実用的な最大値として 256 MB を推奨しています。

デジタル署名（Premium）

キー	環境変数（主）	デフォルト	効果
`signature.enabled`	`NEXTPDF_SIGN_ENABLED`	`false`	false の場合（または証明書が空の場合）、`SignerInterface` の解決先は `null`
`signature.certificate`	`NEXTPDF_SIGN_CERT`	`null`	署名証明書のパス
`signature.private_key`	`NEXTPDF_SIGN_KEY`	`null`	秘密鍵のパス
`signature.password`	`NEXTPDF_SIGN_PASSWORD`	（空）	鍵のパスフレーズ
`signature.extra_certs`	—	`[]`	中間 CA 証明書のパス
`signature.level`	`NEXTPDF_SIGN_LEVEL`	`B-B`	署名者に渡される PAdES ベースラインレベル

ここで説明する Core パッケージには署名者の具象実装は含まれていません。nextpdf/premium が署名者を提供するまでは、SignerInterface バインディングは null に解決されます。Premium では、level: B-B により PAdES B-B ベースライン署名が生成されます。より上位の PAdES ベースラインは、構成済みのタイムスタンプ局と Premium の機能に依存します。このページではそれらのレベルについては説明しません。

タイムスタンプ局

キー	環境変数（主）	デフォルト	効果
`tsa.url`	`NEXTPDF_TSA_URL`	`null`	TSA エンドポイント。空の場合、`TsaClient` の解決先は `null`
`tsa.username` / `tsa.password`	`NEXTPDF_TSA_USERNAME` / `_PASSWORD`	（空）	TSA の HTTP 認証情報
`tsa.cert` / `tsa.key`	`NEXTPDF_TSA_CERT` / `_KEY`	`null`	TSA への mTLS 用クライアント証明書/鍵
`tsa.timeout`	`NEXTPDF_TSA_TIMEOUT`	`30`	PSR-18 クライアントの HTTP タイムアウト（秒）
`tsa.pinned_public_keys`	—	`[]`	Base64 形式の SHA-256 SPKI ピン（RFC 7469）。空にするとピン留めが無効
`tsa.warn_on_key_rotation`	`NEXTPDF_TSA_WARN_ROTATION`	`true`	TSA がピン留めされていない SPKI を提示した場合の警告
`tsa.allow_insecure_http`	`NEXTPDF_TSA_ALLOW_INSECURE_HTTP`	`false`	TSA への平文 HTTP の許可。本番環境では false のままにすること

OCSP レスポンスキャッシュ

キー	環境変数（主）	デフォルト	効果
`ocsp_cache.enabled`	`NEXTPDF_OCSP_CACHE_ENABLED`	`true`	検証中の OCSP レスポンスキャッシュ
`ocsp_cache.ttl`	`NEXTPDF_OCSP_CACHE_TTL`	`86400`	キャッシュの TTL（秒）
`ocsp_cache.directory`	`NEXTPDF_OCSP_CACHE_DIR`	`null`	キャッシュディレクトリ。`null` の場合はメモリ内のみで保持

キュー

キー	環境変数（主）	デフォルト	効果
`queue.connection`	`NEXTPDF_QUEUE_CONNECTION`	`null`	キュー接続。`null` の場合はデフォルト接続を使用
`queue.queue`	`NEXTPDF_QUEUE_NAME`	`pdf`	キュー名。`GeneratePdfJob` のプッシュ先
`queue.timeout`	`NEXTPDF_QUEUE_TIMEOUT`	`120`	ジョブごとのタイムアウト（秒）

Chrome CDP レンダラー（Artisan 拡張）

キー	環境変数（主）	デフォルト	効果
`artisan.chrome_binary`	`NEXTPDF_ARTISAN_CHROME_BINARY`	環境変数の値、または未設定	Chrome/Chromium バイナリへのパス
`artisan.render_timeout`	`NEXTPDF_ARTISAN_RENDER_TIMEOUT`	`30`	レンダリングのタイムアウト（秒）
`artisan.default_css`	`NEXTPDF_ARTISAN_DEFAULT_CSS`	（空）	レンダリングされた HTML に注入されるデフォルト CSS
`artisan.no_sandbox`	`NEXTPDF_ARTISAN_NO_SANDBOX`	`false`	Chrome サンドボックスの無効化
`artisan.max_html_size`	`NEXTPDF_ARTISAN_MAX_HTML_SIZE`	`5000000`	HTML 入力の最大サイズ（バイト）

この artisan セクションは、Chrome ブラウザーファクトリクラスが存在する場合（nextpdf/artisan 拡張）にのみ、ドキュメントバインディングへ適用されます。存在しない場合、このセクションは無視されます。

コードサンプル — 本番環境

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

エッジケースと落とし穴

signature.enabled = true であっても、signature.certificate が空のままでは、SignerInterface は null に解決されます。両方を設定する必要があります。
tsa.url = null にすると、TsaClient は強制的に null になります。これは、他の tsa.* キーが設定されていても同様です。
signature.level = null は、署名者側で PAdES B-B にフォールバックします。
image_cache_mb に null を設定すると（0 ではなく）、50 MB のデフォルト値にフォールバックします。0 は明示的にキャッシュを無効にします。
レガシーの TCPDF_* 環境変数は引き続き読み取られますが、非推奨です。NEXTPDF_* に移行してください。

パフォーマンス

構成の読み取りは O(1) の配列アクセスです。preload_fonts は、ワーカー起動時に 1 回だけ行う O(f) の解析と引き換えに、初回リクエストのレイテンシを低減します。image_cache_mb を大きくすると、プロセス常駐メモリと引き換えに、繰り返し発生する画像デコードを削減します。

セキュリティに関する注意

tsa.allow_insecure_http はタイムスタンプの信頼性を弱めるため、本番環境では false のままにする必要があります。TSA の URL は信頼できる構成からのみ取得すべきです。管理画面経由で設定可能にする場合は、リクエスト偽造を緩和するために egress ファイアウォールまたは DNS ポリシーを適用してください。/integrations/laravel/security-and-operations/ を参照してください

準拠

構成ファイルの形式を定める規範的な標準はありません。すべてのキーは、記載されたリビジョンのパッケージ config/nextpdf.php に対して検証されています。署名レベルのセマンティクスは Premium によって規定されており、この Core ページの範囲外です。

商用に関する背景

signature セクションと tsa セクションは、nextpdf/premium がインストールされている場合に Premium の署名機能を駆動します。これはオプションの Enterprise 機能です。ここで説明する Core パッケージでは、これを利用するためのコード変更は不要です。https://nextpdf.dev/get-license/?intent=laravel-signing を参照してください。