Support: 共有ユーティリティ + Clock + Sleeper

概要

Support モジュールは、エンジンが内部で使用する横断的なユーティリティを提供します。また、小規模な公開サーフェスとして、PSR-20 のシステムクロック、警告収集パイプライン、PDF シリアライズプリミティブも提供します。この名前空間の大部分は内部インフラストラクチャです。このページでは、外部の呼び出し元が依存してよい部分を示し、内部専用の部分にはその旨を明記しています。

インストール

composer require nextpdf/core:^3

概念の概要

Clock (PSR-20)。 SystemClock は Psr\Clock\ClockInterface を実装します。その now() は、現在時刻を DateTimeImmutable として返します。PSR-20 モデルは、1 つの読み取り操作を持つクロックインターフェイスを定義します。この操作は、現在時刻を不変の日時値として返します（PSR-20 psr_20_clock#2.1）。SystemClock がデフォルトです。クロックが注入されていない場合、エンジンはこれを使用します。テストで固定時刻を使う場合は、代わりに固定クロックを注入してください。その固定クロックは同じインターフェイスを実装している必要があります。バイト単位で同一の出力を得るには、クロックを Config::deterministic と組み合わせてください。

警告パイプライン。 WarningCollector は、致命的でないレンダリング上の問題を運ぶ主要なインメモリトランスポートです。エンジンは、決定論的な機能低下が発生するたびに Warning を追加します。例としては、圧縮されたテーブル列、resolve（解決）できないフォント、欠落したグリフなどがあります。呼び出し元は、生成後に Document::getWarnings() を通じてこれらを読み取ります。Warning は不変の値オブジェクトです。WarningCode、WarningSeverity（warning または degraded）、ページ、要素タイプ、機能 ID、機能低下パリティフラグ、メッセージ、DegradationImpact、およびオプションの機能 ID を保持します。WarningCode は、安定した識別子を表す文字列バック列挙型です。これらの識別子には NEXTPDF_W_ という接頭辞が付きます（例: NEXTPDF_W_FONT_UNRESOLVED）。この接頭辞により、テストで安全にマッチングできます。addWithPolicy() は、有効な DegradationPolicy を適用します。strict ポリシーでは、コンプライアンス、セマンティック、またはブロッキングの影響により DegradedException がスローされます。balanced ポリシーでは、ブロッキングの影響のみがスローされます。permissive ポリシーでは、スローされることはありません。

PDF プリミティブ。 PdfStringEscaper は、PDF の文字列および名前のエスケープに関する唯一の信頼できる情報源です。escapeLiteral() は、PDF リテラル文字列で必要となる文字（逆ソリダス、括弧、CR、LF、HT、BS、FF）をエスケープし、NUL を除去します。escapeName() は、名前オブジェクトについて、印字可能 ASCII と PDF 区切り文字セットの範囲外にあるバイトを 16 進エンコードします。BinaryBuffer は、書き込みに最適化されたバイナリアキュムレーターです。PDF オブジェクトとストリームの構築に使います。ストリーミングモードでは、大きなドキュメントを扱う際に php://temp ハンドルへスピルします。また、署名の埋め込みに必要なバイト範囲操作もサポートします。PdfOperators は、コンテンツストリーム演算子のフォーマット文字列（パス、テキスト、グラフィックス状態、フォント）を保持します。描画レイヤーとパーサーレイヤーがこれらを共有します。

BinaryBuffer、PdfOperators、および NextPDF\Support\ の残りの大部分は 内部インフラストラクチャ です。ライターレイヤーと描画レイヤーがこれらを使用します。ここでは、網羅性と監査のために記載しています。これらは、サポート対象の公開 API サーフェスには含まれません。代わりに、Document ファサードと Contracts 名前空間に依存してください。SystemClock、WarningCollector、Warning、WarningCode、WarningSeverity、および DegradationImpact が公開向けのメンバーです。

API サーフェス

シンボル	種別	可視性	主要メンバー
`NextPDF\Support\SystemClock`	final class	public	`now(): DateTimeImmutable` (PSR-20 `ClockInterface`)
`NextPDF\Support\WarningCollector`	final class	public	`add()`, `emit()`, `addWithPolicy()`, `getWarnings()`, `hasWarnings()`, `hasDegradedParity()`, `clear()`
`NextPDF\Support\Warning`	final readonly class	public	`$code`, `$severity`, `$page`, `$elementType`, `$featureId`, `$degradedParity`, `$message`, `$impact`, `$capabilityId`
`NextPDF\Support\WarningCode`	string enum	public	安定した `NEXTPDF_W_*` 識別子
`NextPDF\Support\WarningSeverity`	string enum	public	`Warning`, `Degraded`
`NextPDF\Support\DegradationImpact`	string enum	public	`Cosmetic`, `LayoutRisk`, `SemanticLoss`, `ComplianceRisk`, `Blocking`
`NextPDF\Support\PdfStringEscaper`	final readonly class	内部	`escapeLiteral()`, `escapeName()` (静的)
`NextPDF\Support\BinaryBuffer`	final class	内部	`write()`, `writeStream()`, `replaceAt()`, `extract()`, `enableStreaming()`, `getContents()`
`NextPDF\Support\PdfOperators`	final class	内部	コンテンツストリーム演算子のフォーマット文字列定数

コードサンプル — クイックスタート

生成後に、収集された警告を読み取ります。

<?php

declare(strict_types=1);

use NextPDF\Support\WarningCollector;

$collector = new WarningCollector();

// The engine appends warnings during rendering. After generation:
if ($collector->hasWarnings()) {
    foreach ($collector->getWarnings() as $warning) {
        \printf(
            "[%s] page %d: %s\n",
            $warning->code->value,
            $warning->page,
            $warning->message,
        );
    }
}

コードサンプル — 本番

決定論的な時刻を得るためにクロックを注入し、機能低下パリティの警告をビルド失敗として扱います。

<?php

declare(strict_types=1);

use NextPDF\Support\SystemClock;
use NextPDF\Support\WarningCollector;
use Psr\Clock\ClockInterface;

// Production uses the real system clock.
$clock = new SystemClock();
$now = $clock->now();          // DateTimeImmutable
$epoch = $now->getTimestamp(); // int

// In tests, swap in any ClockInterface that returns a fixed instant
// (the parameter is typed to the PSR-20 interface, not SystemClock).
function buildReport(ClockInterface $clock): \DateTimeImmutable
{
    return $clock->now();
}

$collector = new WarningCollector();
// ... run generation ...
if ($collector->hasDegradedParity()) {
    throw new \RuntimeException('Output parity degraded; failing the build.');
}

エッジケースと注意点

SystemClock::now() は、呼び出しのたびに新しい DateTimeImmutable を返します。2 回の呼び出しが同じ瞬間を返すと想定しないでください。固定時刻には、固定クロックを注入してください。
WarningCollector はインメモリで、インスタンスごとに保持されます。これが主要なチャネルです。JSON サイドカーと CLI STDERR は、コレクター自体ではなく、出力境界で発行されます。
addWithPolicy() は、strict ポリシーの下でレンダリングの途中に DegradedException をスローすることがあります。部分的な出力が必要な場合は、生成境界でこれをキャッチしてください。
WarningCode の値は安定した文字列です。メッセージテキストではなく列挙型のケースでマッチングしてください。メッセージテキストは人間が読めるものであり、変更される可能性があります。
BinaryBuffer::getLength() は、ストリームインターフェイスとの整合性を保つための getOffset() の意図的なエイリアスです。どちらも同じバイト数を返します。
次の PdfStringEscaper、BinaryBuffer、および PdfOperators は内部として扱ってください。これらは、公開 API の安定性保証の対象外です。

パフォーマンス

SystemClock::now() は、単一のオブジェクト構築であり、O(1) です。WarningCollector への追加は、ならし計算量で O(1) のリスト追加です。getWarnings() は、バッキングリストを返します。ストリーミングモードの BinaryBuffer は、ディスクにスピルする前にメモリを maxmemory しきい値（デフォルト 2 MB）までに制限するため、大きなドキュメントでもピークメモリが一定に保たれます。このリファレンスページのデフォルトの performance_budget は wall_ms: 1500、peak_mb: 64 です。

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

クロックサーフェスを使用すると、Config::deterministic と併せて固定クロックを注入することで、署名済みおよびタイムスタンプ付きの出力から実時間の非決定性を取り除くことができます。PdfStringEscaper は、PDF の文字列および名前出力に対する唯一の監査可能なエスケーパーです。すべての文字列出力をこれに通すことで、ユーザー提供のテキスト内にあるエスケープされていない括弧や区切り文字によるコンテンツインジェクションを防止します。警告には、ドキュメント由来の詳細（要素タイプ、機能 ID）が含まれる場合があります。信頼性の低いログシンクに転送する前に、警告出力をスクラブしてください。

準拠

仕様	条項	トピック
PSR-20 (PHP-FIG)	`psr_20_clock#2.1`	クロックの読み取り操作は、不変の日時を返す
ISO 32000-2:2020	§7.3.4.2 / §7.3.5	リテラル文字列および名前オブジェクトのエスケープ（言い換え。ISO の本文は引用しておらず、チャンクのピン留めもなし）

SystemClock は、PSR-20 の ClockInterface を実装します。エスケーパーは、PDF のリテラル文字列および名前オブジェクトの文字規則に従います。ISO のテキストは、サイトの引用ポリシーに従って言い換えられており、逐語的なチャンクはピン留めされていません。