レンダリングおよび I/O のエラー
これらのエントリは、HTML パイプラインがコンテンツをレイアウトし、ページドメディアリゾルバーがページジオメトリを割り当て、テキストシェイパーが複雑なスクリプトを処理し、タイポグラフィステージが行を分割し、ライターがドキュメントをシリアライズし、リーダーが既存の PDF をパースし、 メタデータステージが Extensible Metadata Platform（XMP）パケットを読み取る際に送出される、レンダリングおよび入出力（I/O）の例外を扱います。
以下には 2 つの基底階層が登場します。その違いは、catch の後に読み取れる診断データを決定します。
NextPdfExceptionはContextAwareExceptionInterface::getContext(): arrayを実装します。基底実装は空の配列を返します。サブクラスは、getContext()をオーバーライドした場合にのみ構造化されたキーを保持します。オーバーライドしないサブクラスは、 それでもpublic readonlyプロパティを通じてデータを公開します。- ここでのいくつかのクラスは、PHP の
RuntimeExceptionを直接継承します。これらはコンテキスト対応ではなくgetContext()メソッドを持ちません。代わりにそのgetMessage()と任意の public プロパティを読み取ってください。
各エントリでは、正確なクラス、トリガー条件、保持するコンテキストキーまたは public プロパティ、そして復旧パスを示します。
HTML レイアウトとページドメディア
「HTML レイアウトとページドメディア」という見出しのセクションUnsplittableContentException
「UnsplittableContentException」という見出しのセクション- 送出される条件。
break-inside: avoidとマークされたコンテンツ（その break 制約がAvoidであるテーブルセル）の測定された高さが、単一ページの使用可能な高さを超える場合に、HTML レイアウトエンジンがこれを送出します。エンジンは avoid-break 制約とページ境界の両方を満たせないため、サイレントにオーバーフローするのではなく失敗します。 - 保持するデータ。
NextPdfExceptionを継承しますがgetContext()をオーバーライドしないため、getContext()は空の配列を返します。診断データはpublic readonlyプロパティにあります。gridRow（int）、gridCol（int）、contentHeight（float、ポイント）、pageHeight（float、ポイント）。メッセージはセルの座標と両方の高さを示します。 - 復旧。 問題のセルの
break-inside: avoid制約を削除するか、 セルのコンテンツを 1 ページに収まるよう減らすか、使用可能な高さがコンテンツに合うようページサイズを大きくするか、そのマージンを減らしてください。
BudgetExceededException
「BudgetExceededException」という見出しのセクション- 送出される条件。 retained モードのレイアウトプリミティブが、アーキテクチャ決定記録
ADR-020 で定義された 4 つのリソース予算ティアの 1 つが破られ、呼び出し側がソフトフォールバックではなくハードフェイルにオプトインした場合にこれを送出します。デフォルトパスは送出しません。
ContainerLayout::acceptChild()がfalseを返し、呼び出し側はブロックレイアウトにフォールバックし、警告が発行されます。この例外は、構成時の検証と、正確な破り方のタプルをアサートするテストのために留保されています。ティアはper-child（捕捉された子のストリームがその上限を超える）、per-container（Tier 1 のノード数予算）、per-document（レイアウトパスまたはネスト深度の予算）、 そしてglobal（SDK 全体の 256 MB のピーク常駐セットサイズの上限）です。 - 保持するデータ。
getContext()をオーバーライドし、アプリケーションパフォーマンスモニタリング（APM）ツールが消費する、安定した 8 キーの形を返します。budgetTier、exceededValue、budgetLimit、containerType、phase、breachOrigin、captureSize、processedItemCount。最初の 4 つのキーは元の v1.0.0 のサブセットであり、常に設定されます。後の 4 つは、コンストラクターがそれらなしで呼び出された場合、nullまたは0がデフォルトになります。getCausalWarningCode()は、（ティア, コンテナータイプ）のタプルを、ソフトフォールバックパスが発行したであろうWarningCodeにマッピングします。 - 復旧。 構成の破りについては、要求された値を文書化された包絡内に戻してください（例: retained ノード予算は
Config::withRetainedNodeBudget()を通じて5,000から100,000を受け付けます）。コンテンツの破りについては、 コンテナーのネストまたはノード数を減らすか、ハードフェイルのサーフェスにオプトインするのではなく、デフォルトのソフトフォールバックのブロックレイアウトに頼ってください。
UnsupportedNamedPageException
「UnsupportedNamedPageException」という見出しのセクション- 送出される条件。 ドキュメントが名前付きの
@page <ident> { … }ルール（page: <ident>プロパティを通じてコンテンツにバインドされる）を宣言した場合に、ページドメディアステージがこれをフェイルクローズで送出します。CSS Paged Media Level 3 §3.4 および Level 4 §3.2 の名前付きページ（:first、:left、:right、:blank疑似クラス、および名前付きのsize:とrotate:のオーバーライドを含む）はパースされますが、それを消費する本番のレイアウトパスは存在しません。ルールを破棄することで生じる、サイレントに不正確なデフォルトのページネーションを出力するのではなく、エンジンは拒否します。 - 保持するデータ。
getContext()をオーバーライドし、page_names（失敗を引き起こした個別の ident のリスト、ソース順）、has_size_override（bool）、has_rotate_override（bool）、has_pseudo_classes（bool）を返します。同じ値は、pageNames、hasSizeOverride、hasRotateOverride、hasPseudoClassespublic プロパティで公開されます。 - 復旧。 名前付きの
@page <ident>ルールと任意のpage: <ident>バインディングを削除し、サポートされている無名の@page { … }ルールとその疑似クラス形式を通じて意図したジオメトリを表現してください。あるいは、完全な名前付きページレイアウトのサポートを実装する将来のリリースにピン留めしてください。
タイポグラフィとテキストシェイピング
「タイポグラフィとテキストシェイピング」という見出しのセクションIcuRequirementException
「IcuRequirementException」という見出しのセクション- 送出される条件。 テキストのセグメンテーションが
International Components for Unicode（ICU）の行分割イテレーターを必要とするものの、require-ICU ポリシーが有効（
NEXTPDF_REQUIRE_ICU=1）で、ext-intl拡張モジュールとIntlBreakIteratorが利用できない場合に、これを送出します。 - 保持するデータ。
RuntimeExceptionを直接継承するため、コンテキスト対応ではなくgetContext()を持ちません。同じコードパスが以前に送出していた汎用例外の厳密な絞り込みであるため、既存のcatch (\RuntimeException)ハンドラーは引き続き機能します。 - 復旧。 ICU の break イテレーターが利用可能になるよう
ext-intlをインストールして有効化するか、 require-ICU ポリシーが必須でない場所で非 ICU のセグメンターにフォールバックするには、NEXTPDF_REQUIRE_ICUを解除してください。
ScriptShaperException
「ScriptShaperException」という見出しのセクション- 送出される条件。 これはスクリプトシェイピングのサービスプロバイダーインターフェイス（SPI）の基底例外です。今日は直接送出されません。代わりに具象サブタイプが送出されます。あらゆるシェイピングの失敗を 1 か所で処理するにはこの型を捕捉してください。
- 保持するデータ。
RuntimeExceptionを直接継承します。コンテキスト対応ではなく、getContext()を持ちません。 - 復旧。 具象サブタイプで分岐してください。現在のリリースで同梱される唯一のサブタイプについては、以下の
NotYetImplementedExceptionを参照してください。
NotYetImplementedException
「NotYetImplementedException」という見出しのセクション- 送出される条件。 すべてのプレースホルダーのスクリプトシェイパーが、具体的なシェイピングが延期されているスクリプト（モンゴル文字とチベット文字）について、その
shape()本体からこれを送出します。シェイピング SPI の継ぎ目はアーキテクチャ的には準備が整っていますが、実際のシェイピングはネイティブスピーカーが検証したフィクスチャを待っています。サイレントな no-op ではなく例外を送出することで、タグ付きアクセシビリティを謳う PDF にシェイピングされていないテキストを出力するのではなく、誤った本番配線を実行時に表面化させます。 - 保持するデータ。
ScriptShaperException（したがってRuntimeException）を継承するため、コンテキスト対応ではなくgetContext()を持ちません。 診断データはそのpublic readonlyプロパティにあります。bcp47LanguageTag（run の BCP-47 タグ、例:mn-Mongまたはbo-Tibt）とmissingCapability（実装が欠いている具体的な能力）です。 メッセージは両方を含みます。 - 復旧。 本番環境で、未実装のスクリプトの run をシェイパーに通さないでください。言語タグを上流で検出し、 別のレンダリングパスにフォールバックするか、該当するスクリプトのシェイピングを実装する将来のリリースにピン留めしてください。
ライター出力プロファイルと暗号化
「ライター出力プロファイルと暗号化」という見出しのセクションPdf14FeatureRejectedException
「Pdf14FeatureRejectedException」という見出しのセクション- 送出される条件。 ドキュメントが PDF 1.4 出力プロファイル（ISO 19005-1:2005 / PDF/A-1）の下で禁止されている機能を含む場合に、ライターがこれを送出します。これは、後の PDF バージョンで導入された構成要素を禁止します。
- 保持するデータ。
NextPdfExceptionを継承しますがgetContext()をオーバーライドしないため、getContext()は空の配列を返します。診断データはそのpublic readonlyプロパティにあります。feature（拒否された機能名）、reason（なぜ禁止されているか）、isoClause（ISO 条項参照）。 メッセージは 3 つすべてを組み合わせます。 - 復旧。 拒否された機能を削除するか PDF 1.4 互換の同等品に置き換えるか、その機能を許可するより高い出力プロファイルをターゲットにしてください。
Pdf20FeatureRejectedException
「Pdf20FeatureRejectedException」という見出しのセクション- 送出される条件。 ドキュメントが strict な PDF 2.0 出力プロファイルの下で禁止されている機能を含む場合に、ライターがこれを送出します。ISO 32000-2:2020 は、 PDF 1.7 がまだ許可していた構成要素を deprecate します。最も顕著なのは Standard 14 Type 1 フォント（§9.6.2）であり、これは準拠する PDF 2.0 ドキュメントで埋め込む必要があります。
- 保持するデータ。
Pdf14FeatureRejectedExceptionと同じ形です。NextPdfExceptionを継承し、getContext()をオーバーライドせず（空の配列を返す）、feature、reason、isoClauseをpublic readonlyプロパティとして公開します。 - 復旧。 拒否された機能を是正してください。例: base 14
フォントを埋め込む。あるいは、存在する場合は文書化された脱出口を取ってください（非埋め込みの
base 14 フォントについては、
Document::allowNonEmbeddedBase14()）。
PublicKeyEncryptionUnsupportedException
「PublicKeyEncryptionUnsupportedException」という見出しのセクション- 送出される条件。 ドキュメントの
encryptionModeがpubkey（公開鍵の受信者リスト）であるとき、ライター側の公開鍵ストリーム本体暗号化のディスパッチが配線される前に、PdfWriter::build()がエントリポイントでこれを送出します。 事前に拒否することで、呼び出し側が暗号化されていると考えていた未暗号化の PDF をサイレントに出力することを防ぎます。 - 保持するデータ。
RuntimeExceptionを直接継承するため、コンテキスト対応ではなくgetContext()を持ちません。同じ箇所が以前に送出していた汎用例外の厳密な絞り込みであるため、既存のcatch (\RuntimeException)ハンドラーは引き続き機能します。 - 復旧。 公開鍵の受信者リストの代わりに、サポートされている暗号化モード（パスワードベースの暗号化）を使用するか、 公開鍵暗号化のサポートを実装するリリースにピン留めしてください。これが送出された場合、出力を暗号化されているものとして扱わないでください。
リーダーとメタデータ入力
「リーダーとメタデータ入力」という見出しのセクションUnsupportedPdfStructureException
「UnsupportedPdfStructureException」という見出しのセクション- 送出される条件。 入力 PDF がサポートされる包絡の外にある場合に、オブジェクトグラフリーダーがこれをフェイルクローズで送出します。リーダーは古典的なクロスリファレンステーブル（ISO 32000-2:2020 §7.5.4）、クロスリファレンスストリーム
（§7.5.8）、オブジェクトストリーム圧縮されたオブジェクト（§7.5.7）、複数リビジョンの
/Prevチェーン（§7.5.6）、そして/XRefStmを介したハイブリッドリファレンスファイル（§7.5.8.4）をサポートします。 その包絡の外にあるものは、部分的または推測のパースではなくこの例外を表面化させます。名前付きコンストラクターは理由のケースにマッピングされます。encrypted()、damagedCrossReference()、cyclicReferenceChain()、nonConformantObjectStream()、irresolvableObjectCollision()、truncatedFile()、crossReferenceOffsetOutOfBounds()。 - 保持するデータ。
RuntimeExceptionを直接継承するため、コンテキスト対応ではなくgetContext()を持ちません。UnsupportedPdfStructureReason型（enum）のpublic readonlyreasonプロパティを公開するため、呼び出し側はメッセージをパースすることなく正確なカテゴリーで分岐できます。オプションのdetail文字列とpreviousの throwable が、限定された機微でないコンテキストを追加することがあります。デフォルトのメッセージは、その理由の情報を漏らさない要約です。 - 復旧。
reasonで分岐してください。EncryptedDocumentの場合は、復号がリーダーの範囲外であるため、読み取り前に復号ステップを実行してください。DamagedCrossReference、TruncatedFile、またはCrossReferenceOffsetOutOfBoundsの場合は、ファイルを不正または不完全として扱い、 ソースを再取得または修復してください。CyclicReferenceChain、NonConformantObjectStream、またはIrresolvableObjectCollisionの場合は、入力が構造モデルに違反しており、そのままでは読み取れません。
PacketTooLargeException
「PacketTooLargeException」という見出しのセクション- 送出される条件。 埋め込み XMP パケットが構成済みのバイト上限を超えた場合に、ストリーミング XMP メタデータリーダーがこれを送出します。これは、エンティティ展開や二次的な膨張スタイルの入力に対する防御的なガードです（ギガバイト規模の埋め込み XMP に対する 128 MB のピーク上限）。
- 保持するデータ。
NextPdfExceptionを継承しますがgetContext()をオーバーライドしないため、getContext()は空の配列を返します。診断データはそのpublic readonlyプロパティにあります。byteCount（観測されたバイト数） とcap（構成済みの上限、バイト単位）。メッセージは両方を報告します。 - 復旧。 過大なメタデータを、悪意のあるものまたは不正なものとして拒否またはスキップしてください。正当なドキュメントが本当により大きなパケットを必要とする場合は、このガードが防ぐために存在するメモリ枯渇のリスクを比較衡量したうえで、構成済みの上限を意図的に引き上げてください。
- Error reference index
- Fonts and tagging troubleshooting —
NotYetImplementedException、ScriptShaperException、IcuRequirementExceptionの症状について。 - PDF/A and PDF/UA validation troubleshooting —
Pdf14FeatureRejectedExceptionとPdf20FeatureRejectedExceptionの症状について。 - Encryption and permissions troubleshooting —
PublicKeyEncryptionUnsupportedExceptionとリーダーのEncryptedDocumentの理由について。