Enterprise エディション

ブランディング — 詳細リファレンス

概要

本ページは NextPDF\Enterprise\Branding モジュールの詳細リファレンスです。このモジュールは評価版の出力にマークを付け、有料の出力には手を加えません。ライセンスから解決された BrandingMode がストラテジーを選択し、BrandingApplicator が解決されたストラテジーをレンダリング済みの PDF バイト列に適用します。有料ライセンスの下では、変換は恒等変換です。出力はバイト単位で変更されず、コードの変更も不要です。評価版のワークフローについては、まずブランディング機能ページをお読みください。

提供状況とライセンス

この機能は NextPDF Enterprise（nextpdf/enterprise）に同梱され、Enterprise ティアのライセンスエンベロープで有効化されます。その権限を持たないデプロイでは、この機能のクラスは読み込まれません。エディションを比較してライセンスを取得する。

このサブシステムは、すべてのエディションにわたる評価版の挙動を支配するため、専用の enterprise.branding 機能コードを持ちます。ブランディングモードは実行時に署名済みライセンスエンベロープから解決され、アプリケーションのフラグがそれを選択することはありません。有料ライセンスはモードを None に解決し、ブランド付き出力を生成することは決してありません。切り替えるべき本番ビルドは存在しません。

パブリック API サーフェス

シンボル	パラメータ	デフォルトの挙動	戻り値	スローまたは失敗	備考
`BrandingMode`	—	`None`（`'none'`）: 変更なし	—	—	文字列バックの enum。`EvaluationWatermark`（`'evaluation'`）が評価版ブランディングを有効化。
`BrandingStrategy`	—	統合ポイントが利用するコントラクト	—	—	インターフェース。呼び出し側が `BrandingMode` を直接分岐することはない。
`BrandingStrategy::isActive`	—	null ストラテジーでは `false`、評価版ストラテジーでは `true`	`bool`	—	`false` は他のすべてのメソッドが恒等値を返すことを意味する。
`BrandingStrategy::buildPageWatermark`	`float $pageWidth`、`float $pageHeight`（ポイント）	非アクティブ時は空文字列、アクティブ時は対角線の透かしオペレータ	`string`	—	ストリームはページ上に `/helvetica` フォントリソースがあることを前提とする。
`BrandingStrategy::decorateProducer`	`string $producer`	非アクティブ時は恒等、アクティブ時は評価版サフィックスを追加	`string`	—	デフォルトのサフィックス: `[EVALUATION]`。
`BrandingStrategy::decorateSubject`	`string $subject`	非アクティブ時は恒等、アクティブ時は評価版プレフィックスを前置	`string`	—	空のサブジェクトはトリムされたマーカーを返す。
`BrandingStrategyFactory::create`	`BrandingMode $mode`、`?EvaluationBrandingConfig $config = null`	`None` を `NullBrandingStrategy` に、`EvaluationWatermark` を `EvaluationBrandingStrategy` にマップ	`BrandingStrategy`	—	静的メソッド。`null` の構成はデフォルトを使用。
`EvaluationBrandingConfig::__construct`	6 個のオプションの名前付きパラメータ（text、suffix、prefix、size、gray、angle）	デフォルト: 48 pt、gray 0.85、45 度	インスタンス	空のテキスト、非正のフォントサイズ、または 0.0–1.0 の範囲外の gray で `InvalidArgumentException`	`final readonly`。不変。
`EvaluationBrandingStrategy`	オプションの `EvaluationBrandingConfig`	透かしとメタデータの装飾を適用	—	—	`final readonly`。`BrandingStrategy` を実装。
`NullBrandingStrategy`	—	すべてのメソッドで恒等	—	—	有料ライセンスの下で選択される。
`BrandingApplicator::apply`	`string $pdfBytes`、`BrandingStrategy $strategy`	非アクティブなストラテジー: 入力をバイト単位で返す。アクティブ: 1 つの増分更新を追加	`string`	アクティブなブランディングを安全に適用できない場合に `BrandingApplicationException`	純粋で決定的なバイト変換。
`BrandingApplicationException`	—	終端的でフェイルクローズドな失敗シグナル	—	—	`SPEC_CODE`（`SPEC-BRANDING-UNAPPLICABLE`）を運ぶ。ファクトリ `unsupportedStructure()`。

エントリーポイントのシグネチャ

enum BrandingMode: string
{
    case None = 'none';
    case EvaluationWatermark = 'evaluation';
}

public static function create(
    BrandingMode $mode,
    ?EvaluationBrandingConfig $config = null,
): BrandingStrategy

public function __construct(
    public string $watermarkText = 'EVALUATION COPY — Not for Production Use',
    public string $producerSuffix = ' [EVALUATION]',
    public string $subjectPrefix = '[EVALUATION] ',
    public float $watermarkFontSize = 48.0,
    public float $watermarkGray = 0.85,
    public float $watermarkAngle = 45.0,
)

public function apply(string $pdfBytes, BrandingStrategy $strategy): string

挙動コントラクト

モードとストラテジーの解決。 BrandingMode を選択するのは — アプリケーションコードではなく — ライセンス状態です。BrandingStrategyFactory::create は None を NullBrandingStrategy に、EvaluationWatermark を EvaluationBrandingStrategy にマップします。統合ポイントは BrandingStrategy インターフェースを利用し、モードを直接検査することは決してないため、ブランディングロジックは一元化されたままです。有料ライセンスの下では null ストラテジーが選択され、出力はブランディングサブシステムがまったくない状態で生成された出力と同一になります。

透かしの生成。 buildPageWatermark は 1 ページ分の PDF コンテンツストリームオペレータを出力します。分離されたグラフィックス状態（q/Q）、/helvetica リソース名を介した標準 14 の Helvetica フォント、塗りつぶしのテキストレンダリングモード、そしてテキストをページ中心を通る対角線状に配置する回転行列です。デフォルトのスタイルは、灰色レベル 0.85 の 48 pt テキストを 45 度回転させたものです。中央揃えは、テキスト幅をグリフ数で近似します。intl が読み込まれている場合は書記素クラスタ、そうでない場合は mbstring を介した Unicode コードポイント、最終的なフォールバックとしてバイト長を用います。設計上、グリフごとのアドバンス幅は参照しません。透かしテキストは、ISO 32000-2:2020 §7.3.4.2 に従って PDF リテラル文字列としてエスケープされます（バックスラッシュと丸括弧）。

メタデータの装飾。 decorateProducer は、プロデューサーサフィックスを /Producer の値に追加します。decorateSubject は、サブジェクトプレフィックスを /Subject の値に前置します。空のサブジェクトはトリムされたマーカーを返すため、サブジェクトメタデータを持たないドキュメントにもマークが付きます。

バイトの適用。 BrandingApplicator::apply は、ブランディング制御の終端の消費者です。非アクティブなストラテジーでは、入力をバイト単位で返します。アクティブなストラテジーでは、ISO 32000-2:2020 §7.5.6 で定義される形状で単一の増分更新を追加します。元のバイト列はそのまま保たれ、追加される本体には、装飾された Info オブジェクト（既存のオブジェクト番号を再利用）、ページごとに 1 つの透かしコンテンツストリームと 1 つの更新されたページオブジェクト、そして /Prev が直前の startxref を指す新しいクロスリファレンスストリーム（/Type /XRef、/W [1 4 2]）が含まれます。この変換は、所与の入力と構成に対して純粋かつ決定的です。

フェイルクローズドコントラクト。 ストラテジーがアクティブな場合、入力はブランド付与可能でなければなりません。%PDF- ヘッダー、/Encrypt エントリなし、オブジェクトストリーム（/ObjStm）なし、クロスリファレンスストリームの末尾、そしてすべてのページから解決可能な /helvetica フォントリソースです。いずれかの違反があれば、ブランド未付与のバイト列を返す代わりに BrandingApplicationException を送出します。呼び出し側はこの例外を終端として扱い、元のマーク未付与のバイト列をコミットしてはなりません。

エッジケースと障害モード

ブランド付き出力は、ライセンス状態が評価版スタイルであることを意味します。これはライセンス状態を反映したものであり、欠陥ではありません。
透かしは設計上、中央揃えで対角線です。本番向けに調整できるものではなく、有料ライセンスによって完全に除去されます。
EvaluationBrandingConfig は、空の透かしテキスト、非正のフォントサイズ、および 0.0–1.0 の範囲外の灰色レベルを InvalidArgumentException で拒否します。
プロデューサー、サブジェクト、または透かしのいずれの変更も生成しないアクティブなストラテジーは、有料に見えるバイト列を出力する代わりに BrandingApplicationException で拒否されます。
使用可能な /MediaBox（欠落または継承）を持たないページは、ISO 216 A4 のデフォルトである 595.276 × 841.890 ポイントで透かしが付与されます。
/Contents は単一参照形式と配列形式の両方がサポートされます。透かしの参照は最後に追加されるため、最前面に描画されます。/Contents を持たないページには 1 つが付与されます。
Info の文字列値は、元の表現のままラウンドトリップします。16 進文字列（UTF-16BE）は 16 進のまま、リテラル文字列はリテラルのままです。欠落したキーは追加され、値に非 ASCII 文字が含まれる場合は 16 進エンコードされます。
暗号化されたドキュメントは拒否されます。/Encrypt の下で文字列オブジェクトを書き換えるには、ドキュメント暗号化キーが必要になるためです。
失敗は安定したコード SPEC-BRANDING-UNAPPLICABLE（BrandingApplicationException::SPEC_CODE）を運ぶため、消費側のパイプラインはブランド付与不能な出力をデッドレター化して監査できます。
このモジュールは暗号操作を実行しません。ライセンスエンベロープの署名検証はライセンスサブシステムに属します。ライセンス詳細リファレンスを参照してください。

適合性

主張	標準	節
増分更新は変更をファイルの末尾に追加し、元の内容をそのまま残す。	ISO 32000-2	§7.5.6
更新のクロスリファレンスセクションは変更されたオブジェクトのみを対象とし、追加されるトレーラは直前のクロスリファレンスセクションを特定する `Prev` エントリを運ぶ。	ISO 32000-2	§7.5.6
リテラル文字列は丸括弧で書かれる。釣り合いの取れていない丸括弧とバックスラッシュはエスケープ処理を要する。	ISO 32000-2	§7.3.4.2

すべての節はパラフレーズされており、NextPDF は規定テキストを複製しません。NextPDF は認証の主張を一切行いません。 アプリケーターは、引用された ISO 32000-2 の形状で増分更新を書き込みますが、これは能力の記述であり、認証された、あるいは独立して検証されたライターではありません。本ページは実行時の挙動のみを記述します。いかなる保証も、適格性や法的効力についての言明も行わず、法的助言を構成しません。評価版またはサブスクリプションの条件は、ライセンス契約によってのみ定義されます。

開発ノート

BrandingMode、BrandingStrategy、両方のストラテジー、および構成は @since 3.0.0 を持ちます。BrandingApplicator と BrandingApplicationException は @since 3.1.0 を持ちます。
このサブシステムはネットワーク呼び出しを行いません。アプリケーターは、書き換える構造フィールドのみを読み取ります。Info 辞書の文字列、ページ辞書、およびクロスリファレンスの末尾です。
ライセンスエンベロープは、その発行者署名をランタイムが検証する署名済みアーティファクトです。ライセンスのプロビジョニング、更新、安全な保存はオペレーターの責任です。
すべての具象型は final です。ストラテジーと構成はさらに readonly です。透かしのスタイルを変更するには、新しい構成インスタンスを構築します。
BrandingStrategy::isActive() が false を返す場合、他のすべてのメソッドから恒等値が返されることが保証されます。呼び出し側はパフォーマンスのためにこれでショートサーキットできます。
透かしストリームは /helvetica リソース名を参照します。Core は自身のブランディングのためにこのリソースを登録します。Core のブランディングを無効化する統合では、リソースが存在することを保証しなければなりません。
アプリケーターはダイジェストを計算しません。呼び出し側は、ブランド付きバイト列をコミットする前に再ダイジェストします。
内部メカニズムの詳細は、ソースリポジトリの内部ドキュメントに留まり、本マニュアルの範囲外です。

公開の境界

本ページは、外部から観測可能な挙動とサポートされるパブリック API サーフェスのみを記述します。内部の名前空間パス、ヘルパークラス、メカニズムテーブル、ランブックのファイル名、チケットプレフィックスは範囲外です。