Legal — 詳細リファレンス

概要

• 連番の Bates 番号スタンプを、ページごとの PDF コンテンツストリームフラグメントとして生成します。
• 3 つの公開型：BatesNumberConfig（不変の構成）、BatesNumberer（エンジン）、BatesPosition（6 ケースの位置列挙型）。
• 各フラグメントは自己完結しています。グラフィックス状態は保存および復元されるため、追加しても既存のページコンテンツを乱しません。
• 出力は決定的です。フラグメントは構成、スタンプテキスト、ページサイズの純粋な関数です。
• このモジュールは例外を送出しません。範囲外の入力は、文書化されたフォールバック規則に従って劣化します。

提供とライセンス

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

機能ごとのライセンスフラグは存在しません。これは Pro エディションの機能です。

composer require nextpdf/pro:^3

公開 API サーフェス

シンボル	パラメータ	既定の挙動	戻り値	送出または失敗する条件	備考
BatesNumberConfig::__construct	string $prefix = '', string $suffix = '', int $startNumber = 1, int $padding = 5, BatesPosition $position = BatesPosition::BottomRight, float $fontSize = 9.0, string $fontFamily = 'Courier', float $opacity = 1.0, bool $useLayer = true, string $layerName = 'Bates Numbers', float $inset = 15.0	不変の外観およびナンバリング構成	BatesNumberConfig	—	11 個のプロパティはすべて public かつ readonly。
BatesNumberConfig::formatNumber	int $pageIndex（0 始まり）	prefix + ゼロ埋め（startNumber + pageIndex）+ suffix	string	—	padding より桁数の多い番号は切り詰められません。
BatesNumberConfig::getRange	int $pageCount	実行分の最初と最後の整形済みスタンプ	array{first: string, last: string}	—	pageCount >= 1 を前提とします。0 のときはページインデックス -1 を整形します。
BatesNumberer::__construct	BatesNumberConfig $config	構成をバインド	BatesNumberer	—	このクラスは final かつ readonly。
BatesNumberer::generate	int $pageCount, array $pageSizes, string $prefix = '', int $startFrom = 1	既定の外観を用いる静的な高速パス	list<string>	—	接尾辞、位置、フォント、不透明度、レイヤーは既定値のまま。
BatesNumberer::generateStreams	int $pageCount, list<array{width: float, height: float}> $pageSizes	ページごとに 1 つの自己完結フラグメント	list<string>	送出しません。サイズエントリの欠落は A4 縦にフォールバック	フラグメント数は pageCount と一致。余分なサイズエントリは無視。
BatesNumberer::buildPageStream	string $text, float $pageWidth, float $pageHeight	1 ページ分のスタンプフラグメントを構築	string	—	q/Q でラップ。スタンプテキストはリテラル文字列構文向けにエスケープ。
BatesNumberer::getConfig	—	バインドされた構成を返す	BatesNumberConfig	—	—
BatesPosition	列挙ケース BottomLeft, BottomCenter, BottomRight, TopLeft, TopCenter, TopRight	文字列バックの位置語彙	—	—	バッキング値はケバブケース（例：bottom-right）。
BatesPosition::coordinates	float $pageWidth, float $pageHeight, float $textWidth, float $inset = 15.0	PDF ネイティブ空間でのスタンプベースラインの X/Y	array{x: float, y: float}	—	原点は左下。上段の行はベースラインを上端から inset だけ離して配置。

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

public function __construct(
    public string $prefix = '',
    public string $suffix = '',
    public int $startNumber = 1,
    public int $padding = 5,
    public BatesPosition $position = BatesPosition::BottomRight,
    public float $fontSize = 9.0,
    public string $fontFamily = 'Courier',
    public float $opacity = 1.0,
    public bool $useLayer = true,
    public string $layerName = 'Bates Numbers',
    public float $inset = 15.0,
) {}

public static function generate(
    int $pageCount,
    array $pageSizes,
    string $prefix = '',
    int $startFrom = 1,
): array
public function generateStreams(int $pageCount, array $pageSizes): array
public function buildPageStream(string $text, float $pageWidth, float $pageHeight): string

public function coordinates(
    float $pageWidth,
    float $pageHeight,
    float $textWidth,
    float $inset = 15.0,
): array

挙動コントラクト

ナンバリング

BatesNumberConfig::formatNumber は startNumber + pageIndex を計算し、その番号をゼロで左詰めして padding 桁にし、prefix と suffix で囲みます。getRange は、あるページ数に対する最初と最後の整形済みスタンプを返します。プロダクション間で継続ナンバリングを連結するために使用します。

フラグメントの構造

各フラグメントは順に、グラフィックス状態の保存（q）、塗り色オペレータ、任意のマークコンテンツ開始、スタンプを配置して表示するテキストブロック、任意のマークコンテンツ終了、復元（Q）から成ります。座標とフォントサイズは小数第 6 位まででシリアライズされるため、同一の入力は同一のバイトを生成します。スタンプテキストは、リテラル文字列に入る前に \、(、) をエスケープします。

フォントのバインド

テキストブロックは固定のフォントリソース名 /BatesFont を選択します。埋め込み先ページのリソース辞書は、その名前を、構成された fontFamily に一致するフォントにマッピングしなければならず、そのファミリーはフォントレジストリで解決される必要があります。フラグメント生成自体はレジストリを一切参照しません。

配置

BatesPosition::coordinates は PDF ネイティブ空間でスタンプベースラインを計算します。原点は左下です。中央および右の配置は、推定テキスト幅（バイト長 × 0.6 × フォントサイズ、等幅の近似）を差し引きます。プロポーショナルフォントやマルチバイトテキストはその推定をずらします。左の配置はそれに依存しません。

レイヤー

useLayer を有効にすると（既定）、フラグメントはテキストを BDC と EMC のマークコンテンツオペレータで囲みます。マークコンテンツ名は /Lyr_<name> の形式で、layerName から単語文字以外をアンダースコアに置き換えて導出されます。この囲みはフラグメントレベルのみです。対応するオプショナルコンテンツグループをドキュメントに登録するステップ（ビューアでレイヤーを切り替え可能にするステップ）は、埋め込み側のライターに属します。

不透明度

1.0 未満の opacity は、より明るいグレースケール塗りとして出力されます。完全に不透明なスタンプは黒でレンダリングされます。

スコープ

エンジンは、構成されたとおりに正確に Bates ナンバリングを適用します。番号が付与されたドキュメントが法廷で証拠採用可能であるとか、法的に有効であるとは主張しません。ナンバリングのスキーム、保持、証拠としての取り扱いは顧客の責任です。手続き上の十分性については、法務およびコンプライアンスのチームにご相談ください。

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

• generateStreams は pageSizes の不一致で送出することはありません。エントリの欠落は A4 縦（595.276 × 841.890 ポイント）にフォールバックし、余分なエントリは無視されます。
• フラグメント数は常に pageCount と一致します。
• padding より桁数の多い番号は切り詰められません。スタンプテキストが単に長くなるだけです。
• getRange は pageCount >= 1 を前提とします。0 のときはページインデックス -1、すなわち startNumber - 1 を整形します。
• 不透明度はグレースケールの明度調整であり、ExtGState の透過ではありません。スタンプの下に重なるコンテンツはブレンドされません。
• \、(、) 以外のスタンプバイトは未エンコードで通過します。非 ASCII テキストのエンコード正当性は、バインドされたフォントに依存します。
• Bates のマークはオーバーレイコンテンツです。ページ上の何かを墨消し、除去、暗号化することはありません。
• このモジュールは暗号操作を一切行いません。FIPS モードでも挙動は変わりません。

準拠

挙動	参照	ステータス
BDC/EMC マークコンテンツオペレータによるレイヤーの囲み	ISO 32000-2:2020 §8.11.3.2	部分的 — フラグメントは囲みを出力するが、オプショナルコンテンツグループの登録は埋め込み側ライターのステップ

これらの行は、このモジュールが準拠して構築されている仕様を記録するものであり、認証ではありません。NextPDF は準拠認証を保持していません。この表はまた、法的有効性や証拠としての十分性を表明するものでもありません。

開発上のノート

• フラグメントは純粋な文字列値です。直接のバイト比較でテストしてください。ドキュメントコンテキストは不要です。
• buildPageStream は public であり、単独でユニットテスト可能です。整形済みテキストと明示的なページ寸法を渡してください。
• プロダクション間の継続ナンバリングでは、前回の実行から startNumber をシードし、getRange の出力をプロダクションログに記録してください。
• レイヤー名は単語文字にサニタイズされます。検査ツールでマークコンテンツ名を読みやすく保つために、ASCII のレイヤー名を推奨します。

公開範囲

このページは、外部から観測可能な挙動とサポートされる公開 API サーフェスのみを文書化します。内部の名前空間パス、ヘルパークラス、メカニズム表、ランブックのファイル名、チケット接頭辞は対象外です。

関連項目

• Legal 機能概要
• Merge — 詳細リファレンス
• Security — 詳細リファレンス