コンテンツにスキップ
NextPDF

compat-legacy の設定

概要

「概要」という見出しのセクション

このアダプターには、3 つの設定領域があります。

  1. ストリクトモード — パラメーターが黙って失われる状況を、例外としてスローされる明示的な失敗に変える監査用トグルです。デフォルトではオフです。
  2. レガシー定数 — TCPDF の K_* / PDF_* 定数です。これらを参照するレガシーコードが動作するよう、6.2.13 のデフォルト値で自動定義されます。
  3. AdaptationConfig — 定数ベースの設定に代わる、最新のイミュータブルな設定オブジェクトです。

ドキュメントの設定は、ほとんどの場合、すでに使っている TCPDF メソッド（SetMargins()、SetFont() など）で行います。以下では、互換レイヤーに固有の設定領域を扱います。

ストリクトモード

「ストリクトモード」という見出しのセクション

ストリクトモードは、移行時に最も重要な設定です。レンダリング結果は変わりません。TCPDF の挙動を再現できない呼び出しを 明示的に失敗させる のか、サイレントに劣化させる のかを制御します。

examples/config-strict.php
<?php


declare(strict_types=1);


require __DIR__ . '/vendor/autoload.php';


use NextPDF\Compat\Tcpdf\TCPDF;


$pdf = new TCPDF();


$pdf->setStrictMode(true);   // audit: throw on silent parameter loss
$isOn = $pdf->isStrictMode(); // true
$pdf->setStrictMode(false);  // back to backward-compatible default

tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php で検証されている挙動は次のとおりです。

モードサイレントに無視されるメソッドの呼び出し結果
オフ（デフォルト）例：追加パラメーター付きの Image()実行され、無視されたパラメーターは効果なし
オン同じ呼び出し無視されたパラメーターを示す TcpdfNotImplementedException をスロー
オンサポート対象のパラメーターのみで呼び出されたサイレント無視メソッドスローしない（例：SetProtection([], 'u', 'o', 0, [])）

ストリクトモードは加算的に働きます。メソッドが特定のパラメーターをサポートしている場合、委譲は引き続き行われます。ストリクトモードは、破棄されるパラメーターに例外ガードを追加するだけです。推奨される使い方は、専用の CI ジョブまたは一度限りの監査パスであり、本番環境ではありません。この考え方は、OWASP ASVS 5.0 のエラー処理における明示的失敗（fail-explicitly）の原則（RAG サイドカーに記録された reference_id 条項）に従っています。つまり、呼び出し側は、自分の意図が尊重されなかった場合にそれを観測できる必要があります。

ストリクトモードを有効にしたまま本番コードを出荷しないでください。サイレントに無視されたパラメーターは開発者体験上の問題であり、ランタイム障害ではありません。 本番のレンダリング経路で発生する例外は、劣化した出力よりも悪い結果につながります。監査し、修正してから、オフにしてください。/integrations/tcpdf-compat/migration/ を参照してください。

レガシー TCPDF 定数

「レガシー TCPDF 定数」という見出しのセクション

レガシー TCPDF は、設定を K_* 定数と PDF_* 定数から読み取ります。アダプターは、構築時に、まだ定義されていない場合に限り、それらを TCPDF 6.2.13 のデフォルト値で自動定義します。アプリケーションが既に定数を定義している場合（たとえばカスタムの K_PATH_FONTS）、その値は保持されます。

主なデフォルトは次のとおりです（全一覧は src/Compat/Tcpdf/Config/LegacyDefaults.php）。

定数デフォルト備考
PDF_PAGE_FORMATA4
PDF_PAGE_ORIENTATIONP
PDF_UNITmm
PDF_MARGIN_LEFT / RIGHT15ユーザー単位
PDF_MARGIN_TOP27ユーザー単位
PDF_MARGIN_BOTTOM25ユーザー単位
PDF_FONT_NAME_MAINhelvetica
PDF_FONT_SIZE_MAIN10
K_CELL_HEIGHT_RATIO1.25
K_TCPDF_CALLS_IN_HTMLfalseハードン済み：常に false。マークアップによって PHP が実行されることはありません
K_TCPDF_THROW_EXCEPTION_ERRORtrueハードン済み：Error() は常にスローし、die() を呼ぶことはありません
K_TIMEZONEUTC

このうち 2 つは安全性のために意図的に固定されており、設定で緩和することはできません。K_TCPDF_CALLS_IN_HTML は常に false であり、K_TCPDF_THROW_EXCEPTION_ERROR は実質的に常に true です。レガシーコードがこれら 2 つの安全でないレガシー挙動のいずれかに依存している場合、そのコードは変更しなければなりません。/integrations/tcpdf-compat/security-and-operations/ を参照してください。

独自の定数を定義する場合は、最初にアダプターを構築する 前 に定義してください（通常はアプリケーションのブートストラップ内）。

examples/config-constants.php
<?php


declare(strict_types=1);


// Define BEFORE constructing the adapter; the adapter will not override it.
define('PDF_CREATOR', 'My Application');
define('PDF_AUTHOR', 'My Application');


require __DIR__ . '/vendor/autoload.php';


use NextPDF\Compat\Tcpdf\TCPDF;


$pdf = new TCPDF();
// Creator and Author are seeded from your constants.

最新の AdaptationConfig オブジェクト

「最新の AdaptationConfig オブジェクト」という見出しのセクション

グローバル定数に依存したくないコード向けに、このパッケージはイミュータブルな設定値オブジェクト NextPDF\Compat\Tcpdf\Config\AdaptationConfig を提供します。これは final readonly であり、すべてのフィールドは TCPDF 6.2.13 の値をデフォルトとします。変更したいフィールドだけを指定して、安全に構築できます。

現在定義されているレガシー定数から構築することもできます。

examples/config-adaptation.php
<?php


declare(strict_types=1);


require __DIR__ . '/vendor/autoload.php';


use NextPDF\Compat\Tcpdf\Config\AdaptationConfig;


// Snapshot the currently-defined legacy constants into an object:
$config = AdaptationConfig::fromLegacyConstants();


echo $config->pageFormat;   // 'A4' unless a constant overrides it
echo $config->fontNameMain; // 'helvetica'
echo $config->marginLeft;   // 15.0

AdaptationConfig は、設定の移行先となるオブジェクトです。呼び出し箇所を最新の API へ移行するにつれて、定数参照を明示的な AdaptationConfig のフィールドに置き換えてください。これにより、設定はグローバルではなく、型付けされたローカルなものになります。

設定の解決順序

「設定の解決順序」という見出しのセクション

アダプターがドキュメントを構築するとき、設定は次の順序で解決されます（後の手順が前の手順を上書きすることはありません）。

  1. コンストラクター引数（orientation、unit、format など）：対象となる値については最も高い優先度。
  2. アプリケーションが既に定義しているレガシー定数。
  3. TCPDF 6.2.13 のデフォルト定数。まだ定義されていないすべての定数は、LegacyDefaults によって自動定義されます。

コンストラクター引数 unicode、encoding、diskcache は、シグネチャ互換のために受け付けられますが、効果はありません。NextPDF は常に Unicode かつ UTF-8 であり、ディスク上のページキャッシュは持ちません。pdfa コンストラクターフラグも受け付けられますが、PDF/A のアーカイブ準拠には商用エディションが必要です（/integrations/tcpdf-compat/security-and-operations/ を参照）。

関連項目

「関連項目」という見出しのセクション
  • src/Compat/Tcpdf/Config/LegacyDefaults.php：正式な定数デフォルト
  • src/Compat/Tcpdf/Config/AdaptationConfig.php：最新の設定オブジェクト
  • /integrations/tcpdf-compat/migration/：グローバル定数からの設定移行
  • /integrations/tcpdf-compat/security-and-operations/：2 つのハードン済みかつ設定不可のフラグ