Inspect: PDF の内観検査とプリフライト

概要

Inspect モジュールは既存の PDF を読み込み、複雑度スコア、フォントと画像の監査、適合性のヒント、リスクフラグとして内容をレポートします。プリフライトポリシーはそのレポートを pass/fail の判定へ変換するため、ドキュメントがパイプラインに入る前にゲートできます。

安定性: experimental（試験的）。 内観検査は現在も進化中のサーフェスです。この InspectResult の形状、リスクフラグの集合、およびオプションの高速化された内観検査パスは、マイナーバージョン間で変更される可能性があります。診断とゲーティングに使用してください。ただし、その結果の形状に対する長期的な契約はまだ固定しないでください。

インストール

composer require nextpdf/core:^3

概念的な概要

Inspector がエントリポイントです。InspectorInterface を実装し、1 つのメソッド inspect(string $pdfData, InspectConfig $config = new InspectConfig()): InspectResult を公開します。読み取り専用であり、PDF を解析してその特徴を捉えますが、ドキュメントを変更することはありません。

InspectResult は構造化されたレポートであり、複雑度スコア、各種監査、ヒント、および RiskFlag の集合を保持します。hasRisks() / hasRisk(RiskFlag $flag) に応答するため、呼び出し側は自由形式のテキストを解析せず、特定のリスクに基づいて分岐できます。ComplexityScore は数値スコアに加えて category() のバンドを公開します。FontAuditEntry と ImageAuditEntry は埋め込みリソースを記述します。ComplianceHint は適合性の問題となりそうな箇所を示します。InspectIssue は具体的な検出結果を記録します。InspectDepth は内観検査の深さを選択し、toSpectrumDepth() は、Spectrum サイドカーが利用可能な場合にそれを高速化されたパスへマッピングします。内観検査はサイドカーがなくても実行されます。サイドカーが変えるのはパフォーマンスだけであり、契約は変わりません。InspectResponseParser は、生のレスポンス（たとえば高速化されたパスのレスポンス）から、オプションのトレース ID 付きで InspectResult を構築します。

PreflightPolicy は判定レイヤーです。evaluate(InspectResult $result) は、設定済みのポリシーを結果に適用し、ポリシーの判定結果を返します。モジュール全体が @since 2.2.0 です。

API サーフェス

型	主なメンバー	役割
`Inspector`	`inspect(string $pdfData, InspectConfig $config): InspectResult`	読み取り専用の PDF インスペクター（`@since 2.2.0`）
`InspectResult`	`hasRisks()`、`hasRisk(RiskFlag)`、score/audit アクセサー	構造化された内観検査レポート（`@since 2.2.0`）
`ComplexityScore`	`category()`	数値の複雑度スコア + バンド（`@since 2.2.0`）
`FontAuditEntry` / `ImageAuditEntry`	リソースアクセサー	埋め込みリソースの監査（`@since 2.2.0`）
`ComplianceHint` / `InspectIssue`	検出結果アクセサー	適合性のヒントと検出結果（`@since 2.2.0`）
`InspectDepth`（enum）	`toSpectrumDepth()`	内観検査の深さ → 高速化されたパス（`@since 2.2.0`）
`PreflightPolicy`	`evaluate(InspectResult): array`、`toArray()`	pass/fail のプリフライト判定（`@since 2.2.0`）
`InspectResponseParser`	`parse(array, InspectConfig, ?string $traceId): InspectResult`	生のレスポンスからの結果構築（`@since 2.2.0`）

完全な PHPDoc テーブルは、composer docs:generate-api-php -- --module=Inspect を実行して確認してください。

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

ソース: examples/34-inspect-layout-boxes.php は、ページのジオメトリを読み取る方法を示します。以下は、任意の PDF のリスクプロファイルを内観検査する例です。

<?php

declare(strict_types=1);

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

use NextPDF\Inspect\Inspector;

$result = (new Inspector())->inspect(file_get_contents('/srv/in/incoming.pdf'));

if ($result->hasRisks()) {
    echo "Complexity: {$result->complexityScore()->category()}; risks present.\n";
}

コードサンプル — 本番

受信した PDF にプリフライトポリシーでゲートをかけ、リスクがあれば拒否します。

<?php

declare(strict_types=1);

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

use NextPDF\Inspect\Inspector;
use NextPDF\Inspect\PreflightPolicy;
use Psr\Log\LoggerInterface;

final readonly class IngestPreflight
{
    public function __construct(
        private Inspector $inspector,
        private PreflightPolicy $policy,
        private LoggerInterface $logger,
    ) {}

    public function accept(string $pdfData): bool
    {
        $result = $this->inspector->inspect($pdfData);
        $verdict = $this->policy->evaluate($result);

        if ($verdict !== []) {
            $this->logger->warning('PDF rejected at preflight.', ['findings' => $verdict]);

            return false;
        }

        return true;
    }
}

エッジケースと落とし穴

inspect() は読み取り専用です。入力を変更したり修復したりすることは決してありません。「修正された」ドキュメントが返ってくることは期待しないでください。
hasRisk(RiskFlag) は厳密なチェックです。hasRisks() だけで分岐すると、すべてのリスクを同一に扱うことになります。通常は特定のフラグが必要です。
InspectDepth はコストを制御します。大きな PDF に対する深い内観検査は著しく遅くなります。確認したい内容に答えられる範囲で、最も浅い深さを選んでください。
Spectrum で高速化されたパスが変えるのはパフォーマンスであり、結果の契約ではありません。高速化されたレスポンスの形状ではなく、InspectResult に対してコードを書いてください。
PreflightPolicy::evaluate() は検出結果を返し、例外をスローしません。空の結果は pass です。戻り値に基づいて処理してください。

パフォーマンス

内観検査のコストは、ドキュメントのサイズと選択した InspectDepth に応じてスケールします。浅い内観検査は高速ですが、大きな PDF の深い監査はバジェットに近づくことがあります。Spectrum パスは、利用可能な場合に重い解析をオフロードします。1500 ms（wall）/ 64 MB（ピーク）という performance_budget が参照ワークロードです。再現性プロファイルは structural です。つまり、結果はトレース ID とタイミングを保持できます。2 回の実行ではそれらのフィールドが異なりますが、同じ入力に対する検出結果は安定しています。

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

Inspector::inspect() は信頼できない PDF バイトを解析します。これこそがこの機能の目的そのものなので、入力は敵対的なものとして扱ってください。ユーザー提供のドキュメントについては、制約されたワーカー内で内観検査を実行し、入力サイズを上流で制限してください。意図的に複雑化された PDF は、深さにかかわらずサービス拒否（DoS）のベクトルとなります。結果はドキュメントを記述しますが、サニタイズはしません。「low risk」の判定はヒューリスティックであり、安全性の保証ではありません。抽出された文字列とメタデータは信頼できないものとして扱ってください。エンジンの脅威モデルについては /modules/core/security/ を参照してください。

適合性

このモジュールは適合性の ヒント を報告するものであり、権威ある適合性判定ではありません。ComplianceHint は問題となりそうな箇所をヒューリスティックに示します。権威ある PDF/A、PDF/UA、および ISO 32000-2 の適合性判定は、/modules/core/cli/ によって駆動される参照バリデーター、および /modules/core/conformance/ に記載されたオラクルおよびゴールデンスイートから得られます。クリーンな Inspect の結果を適合性の認証として扱わないでください。