ข้อผิดพลาด core และทั่วไป

ขอบเขต

รายการเหล่านี้ครอบคลุม exception หมวด core และทั่วไปที่ NextPDF ยกขึ้น ส่วนใหญ่สืบทอดจากฐาน NextPdfException ซึ่งตัวมันเองสืบทอดจาก \RuntimeException และนำ ContextAwareExceptionInterface ไปใช้ อินเทอร์เฟซ นั้นเปิดเผยเมธอดเดียวคือ getContext(): array ที่คืนแมป snake_case แบบแบนของค่า พื้นฐานที่ปลอดภัยต่อการ serialize ลงในล็อกหรือ payload ของ APM

จับตระกูล NextPdfException ด้วย catch (NextPdfException $e) เดียว เพิ่ม catch (\RuntimeException $e) ด้วยเพื่อครอบคลุมข้อผิดพลาดระดับล่างไม่กี่ตัวใน ชุดนี้ที่สืบทอดจาก \RuntimeException โดยตรง (ระบุไว้ด้านล่าง) ฐาน NextPdfException::getContext() คืนอาร์เรย์ว่าง ซับคลาสเขียนทับมัน เพื่อเพิ่มฟิลด์เฉพาะโดเมน เมื่อคลาสไม่เขียนทับ getContext() มันจะ สืบทอดอาร์เรย์ว่างและรายละเอียดการวินิจฉัยจะอยู่ในข้อความและ getter แบบมีชนิดแทน

ชนิดสี่ตัวในชุดนี้ ไม่ สืบทอดจาก NextPdfException: BlackPointCompensationUnsupportedException และ UnsupportedSourceDocumentException สืบทอดจาก \RuntimeException โดยตรง (จับเป็น \RuntimeException) ส่วน ComplianceViolation และ RuleViolation เป็น value object ไม่ใช่ exception แต่ถูกบันทึกไว้ที่นี่ เพราะมันจำลองข้อมูลข้อผิดพลาดและการละเมิดที่เอนจินคืนมา

ข้อยกเว้นฐาน

NextPdfException

• มันคืออะไร ฐาน abstract สำหรับทุก exception ที่ NextPDF core และแพ็กเกจส่วนขยายยกขึ้น มันสืบทอดจาก \RuntimeException และนำ ContextAwareExceptionInterface ไปใช้ การจับชนิดเดียวนี้จะดักจับข้อผิดพลาด ใดๆ ของไลบรารี
• Context ฐาน getContext() คืนอาร์เรย์ว่าง ซับคลาส เขียนทับมันเพื่อคืนฟิลด์เฉพาะโดเมน
• Recovery ไม่ถูกยกโดยตรง ใช้มันเป็นชนิด catch-all แล้วแยกกิ่งตาม ซับคลาสที่เป็นรูปธรรมสำหรับการจัดการเฉพาะ

การกำหนดค่าและการควบคุมฟีเจอร์

InvalidConfigException

• ถูกยกเมื่อใด เมื่อค่า Config หรือชุดค่าผสมไม่ถูกต้อง — การตั้งค่าที่ จำเป็นแต่ขาดหายไป ตัวเลือกที่เป็น mutually exclusive หรือค่าที่ อยู่นอกช่วงที่ยอมรับ นี่สื่อถึงข้อผิดพลาดของนักพัฒนา: โค้ดที่เรียก ป้อนการกำหนดค่าที่ต้องแก้ไขก่อนลองใหม่ ข้อความ รายงานคีย์ ชนิดหรือช่วงที่คาดหวัง และชนิด debug จริงของ ค่าที่ป้อน
• Context getContext() คืน config_key, given_value, และ expected_type getter แบบมีชนิด: getConfigKey(), getGivenValue(), getExpectedType()
• Recovery การกระทำของนักพัฒนา: แก้คีย์การกำหนดค่าที่ระบุชื่อให้เป็นค่า ที่อยู่ในชนิดหรือช่วงที่คาดหวังก่อนเรียก NextPDF อีกครั้ง

NotImplementedException

• ถูกยกเมื่อใด เมื่อมีการมาถึงจุดเข้า public API แต่ การนำไปใช้ของมันถูกละไว้โดยเจตนาในรีลีสปัจจุบัน ใช้สำหรับ shim ที่เลิกใช้แล้วซึ่งมีอยู่เพื่อให้ผู้เรียกก่อน bisect ได้รับความล้มเหลวที่ ดังและทำตามได้แทน no-op เงียบๆ ข้อความรวม ป้าย feature ที่ grep ด้วยเครื่องได้และการอ้างอิง followUp (รหัสข้อบกพร่อง จุดติดตาม หรือ ชื่อ sprint)
• Context ไม่เขียนทับ getContext() จึงคืนอาร์เรย์ว่าง ค่า $feature และ $followUp เป็นพร็อพเพอร์ตี public readonly และ ฝังอยู่ในข้อความ
• Recovery การกระทำของผู้เรียกไลบรารี: ลบการเรียกออก หรือ pin ไปยังรีลีส ในอนาคตที่มี follow-up ที่ระบุชื่อนั้น

IncompatibleFeatureFlagsException

• ถูกยกเมื่อใด ที่เวลาสร้าง Config (Config::validate()) เมื่อชุด CssFeatureFlags ไม่สอดคล้องกันภายใน — flag หนึ่ง สันนิษฐานอีก flag หนึ่งที่ถูกปิดอยู่ ชุดค่าผสมที่ต้องห้ามเพียงชุดเดียวในวันนี้คือ layoutSubgrid = true กับ layoutGrid = false: แกนแบบ subgrid จะ อนุมานเส้นกริดของมันจาก grid container แม่ (CSS Grid Layout Module Level 2 §1) ดังนั้น subgrid โดยไม่มี grid จึงอธิบายกริดที่ไม่อาจมีอยู่ได้ การตรวจ ทำงานกับ flag ที่ resolve แล้ว ดังนั้น CssRenderingMode::Safe (ซึ่งบังคับให้ทุก คุณสมบัติ Phase 4+ ปิด) จะ mask ชุดค่าผสมแทนการทำให้สะดุด สืบทอดจาก StrictModeViolation
• Context getContext() ผสานฟิลด์ strict-mode ของแม่ (cssDeviation, excId, chunkSha256, location) เข้ากับ boolean layoutGrid และ layoutSubgrid ค่า location คือ Config::validate() และ cssDeviation เข้ารหัสคู่ flag
• Recovery การกระทำของผู้เรียกไลบรารี: เปิด layoutGrid ควบคู่กับ layoutSubgrid หรือปิด layoutSubgrid

IncompatibleRenderingModeException

• ถูกยกเมื่อใด ที่เวลาสร้าง Config เมื่อการจับคู่ CssRenderingMode และ CssLayoutMode ตกอยู่นอกเซลล์ที่เข้ากันได้ของเมทริกซ์โหมด การจับคู่ที่ต้องห้ามเพียงคู่เดียวในวันนี้คือ CssRenderingMode::Safe + CssLayoutMode::Retained — Safe บังคับให้ทุกคุณสมบัติ Phase 4+ ปิด ทำให้ formatting context แบบ retained-mode (Grid, Subgrid, @container) ไม่มี ผู้บริโภค ชุดค่าผสมนี้จึงถูกปฏิเสธแทนที่จะปล่อยให้ลดทอนลง อย่างเงียบๆ สืบทอดจาก StrictModeViolation
• Context getContext() ผสานฟิลด์ strict-mode ของแม่เข้ากับ mode1 (ค่า rendering-mode) และ mode2 (ค่า layout-mode) ค่า cssDeviation เข้ารหัสคู่โหมด location คือ Config::validate()
• Recovery การกระทำของผู้เรียกไลบรารี: เลือก Safe + Streaming สำหรับการ rollback หรือ rendering mode ที่ไม่ใช่ Safe (Normal / Strict / Audit) กับ Retained สำหรับ Grid / Subgrid / Container Queries

StrictModeViolation

• ถูกยกเมื่อใด ฐาน abstract สำหรับ exception การเบี่ยงเบนจากสเปกใดๆ ที่ถูกยก ภายใต้ CssRenderingMode::Strict ในโหมด strict การเบี่ยงเบน CSS ใดๆ ที่ตรวจพบ ซึ่งไม่ผูกกับรายการ exception EXC-NNN ที่ลงทะเบียนไว้จะยกอินสแตนซ์ของ คลาสนี้ (หรือซับคลาส) ที่จุดตรวจจับ ไม่ถูกยกโดยตรง ดู IncompatibleFeatureFlagsException และ IncompatibleRenderingModeException
• Context getContext() คืนสี่ฟิลด์ของ ADR-023: cssDeviation (ป้ายสั้นสำหรับ construct ที่เบี่ยงเบน) excId (ตัวระบุ registry เมื่อ ลงทะเบียน มิฉะนั้น null) chunkSha256 (แฮชของ chunk การอ้างอิงสเปกเมื่อทราบ มิฉะนั้น null) และ location (ต้นทางที่ผู้เรียกอ่านได้ มิฉะนั้น null)
• Recovery การกระทำของผู้เรียกไลบรารี: ลงทะเบียนการเบี่ยงเบนเป็นรายการ EXC-NNN ที่ลงนามใหม่ หรือแก้ไขตัวเรนเดอร์เพื่อกำจัดการเบี่ยงเบน

อินพุต HTML และ CSS

HtmlParsingException

• ถูกยกเมื่อใด เมื่อการแยกวิเคราะห์ HTML input หรือการสร้าง DOM ล้มเหลว: การประกาศ charset ที่ไม่ถูกต้อง การละเมิดขีดจำกัดขนาด input ความลึกของ nesting ที่ มากเกินไป การล้นของจำนวนเอลิเมนต์ และข้อผิดพลาดโครงสร้างตาราง เช่น จำนวน แถวสูงสุด การหมดทรัพยากรเฉพาะ CSS จะถูกรายงานโดย CssParserLimitExceededException และ CssResolutionBudgetExceededException แทน
• Context getContext() คืน html_snippet (ส่วนตัดทอนสั้นๆ ของ HTML ที่เป็นปัญหา) position (ออฟเซ็ตเป็นไบต์ หรือ -1 หากไม่ทราบ) และ rule (ข้อจำกัด parser ที่ถูกละเมิด) getter แบบมีชนิด: getHtmlSnippet(), getPosition(), getRule()
• Recovery การกระทำของนักพัฒนา: ทำให้ HTML input ง่ายขึ้นหรือปรับขีดจำกัด ของ parser

CssParserLimitExceededException

• ถูกยกเมื่อใด เมื่อ CSS input เกินขีดจำกัดความปลอดภัยของ parser ที่กำหนดค่าไว้ มีสองหมวดหมู่ที่ครอบคลุมผ่าน constructor ที่ระบุชื่อ: forByteLimit() (สไตล์ชีตใหญ่เกินไปสำหรับการประมวลผล regex อย่างปลอดภัย) และ forNestingDepth() (การ recursion ของ CSS nesting ลึกเกินไป) ทั้งสองข้อความระบุชื่อ ค่าจริงและขีดจำกัด
• Context getContext() คืน limit_type (byte หรือ nesting_depth), actual, และ limit
• Recovery การกระทำของนักพัฒนา: แบ่งสไตล์ชีตเป็นชีตเล็กลง หรือ ลดความลึกของ nesting หรือเพิ่มขีดจำกัดที่กำหนดค่าไว้

CssResolutionBudgetExceededException

• ถูกยกเมื่อใด เมื่อการ resolve CSS :has() เกินงบประมาณการ traverse ของมัน ตัว resolver :has() แบบสองรอบบังคับใช้งบประมาณการเยี่ยม node อย่างเข้มงวด เพื่อป้องกันไม่ให้ selector ที่ผิดปกติทำให้เกิดการเดินเอกสารแบบกำลังสอง เมื่อ จำนวนการเยี่ยมรวมเกินขีดจำกัด สไตล์ชีตจะถูกปฏิเสธเพราะซับซ้อน เกินไป ข้อความระบุชื่อจำนวนการเยี่ยมและงบประมาณ
• Context getContext() คืน visits และ budget getter แบบมีชนิด: getVisits(), getBudget()
• Recovery การกระทำของนักพัฒนา: ลดความซับซ้อนของ selector หรือเพิ่ม งบประมาณที่กำหนดค่าไว้

ฟอนต์และรูปภาพ

FontNotFoundException

• ถูกยกเมื่อใด เมื่อไฟล์ฟอนต์ไม่อาจระบุตำแหน่งหรืออ่านได้ที่ระดับ ระบบไฟล์: family หรือ path ที่ร้องขอไม่มีอยู่ ไม่อาจ อ่านได้ หรือไดเรกทอรีฟอนต์ที่กำหนดค่าไว้เข้าถึงไม่ได้ ข้อมูลฟอนต์อาจ ถูกต้อง — นี่สื่อเพียงว่าไม่อาจเข้าถึงมันได้ ข้อความแสดงรายการ path ที่ค้นหา
• Context getContext() คืน font_name, search_paths (รายการ) และ fallback_attempted (bool) getter แบบมีชนิด: getFontName(), getSearchPaths(), wasFallbackAttempted()
• Recovery การกระทำของนักพัฒนา: ตรวจสอบ path ของฟอนต์ การกระทำด้านโครงสร้างพื้นฐาน: แก้สิทธิ์ของไฟล์บนไฟล์ฟอนต์หรือไดเรกทอรี

FontParsingException

• ถูกยกเมื่อใด เมื่อพบไฟล์ฟอนต์แต่เนื้อหาไม่ ใช้งานได้: มันเสียหาย อยู่ในรูปแบบที่ไม่รองรับ หรือขาดตารางที่จำเป็น ครอบคลุมความล้มเหลวของการตรวจสอบยืนยันโครงสร้างระหว่างการแยกวิเคราะห์ TrueType, Type 1, CFF, และ OpenType — header ที่ถูกตัดทอน table directory ที่ไม่ถูกต้อง ตาราง บังคับที่ขาดหายไป (head, hhea, OS/2) ข้อผิดพลาดการ unpack และการละเมิด ขนาด ข้อความระบุชื่อไฟล์และข้อผิดพลาดการแยกวิเคราะห์
• Context getContext() คืน font_file และ parse_error getter แบบมีชนิด: getFontFile(), getParseError()
• Recovery การกระทำของนักพัฒนา: แทนที่ไฟล์ฟอนต์ด้วยไฟล์ที่ถูกต้อง

ImageProcessingException

• ถูกยกเมื่อใด เมื่อรูปภาพไม่อาจถอดรหัสได้ อยู่ในรูปแบบที่ ไม่รองรับ หรือล้มเหลวในการประมวลผล GD/Imagick: magic byte ที่ไม่รู้จัก JPEG ที่ เสียหาย ชนิด MIME ที่ไม่รองรับ การละเมิดขีดจำกัดขนาดไฟล์ และความล้มเหลว ในการจัดสรรทรัพยากร GD รูปภาพเข้าถึงได้แต่ข้อมูลพิกเซลของมันไม่อาจ ดึงมาฝังได้
• Context getContext() คืน image_path (ว่างสำหรับข้อมูล inline), format (ที่ตรวจพบหรือคาดหวัง เช่น jpeg, png, unknown) และ operation (เช่น decode, resize, embed) getter แบบมีชนิด: getImagePath(), getFormat(), getOperation()
• Recovery การกระทำของนักพัฒนา: จัดหาไฟล์รูปภาพที่ถูกต้องและรองรับ

เอาต์พุต เลย์เอาต์ และการซีเรียลไลซ์

CompressionException

• ถูกยกเมื่อใด เมื่อการบีบอัดหรือคลายการบีบอัด FlateDecode (zlib) ล้มเหลว — ความล้มเหลว gzcompress/gzuncompress บน content stream ข้อมูลฟอนต์ เนื้อหาหน้า ข้อมูลไฟล์แนบ และ cross-reference stream โดยทั่วไปคือ input stream ที่เสียหาย หน่วยความจำไม่เพียงพอ หรือส่วนขยาย zlib ที่ขาดหายไป
• Context getContext() คืน algorithm (ชื่อ filter เช่น FlateDecode, LZWDecode) และ stream_length (ความยาวเป็นไบต์ หรือ -1 หาก ไม่ทราบ) getter แบบมีชนิด: getAlgorithm(), getStreamLength()
• Recovery การกระทำด้านโครงสร้างพื้นฐาน: ตรวจสอบว่า ext-zlib ถูกโหลดและหน่วยความจำ เพียงพอ

WriterException

• ถูกยกเมื่อใด เมื่อการ serialize PDF การ linearize หรือเอาต์พุต I/O ล้มเหลว: ข้อผิดพลาดการเขียน stream ของ PdfWriter การเสียหายของตาราง cross-reference ความล้มเหลวการสร้าง header/trailer ความล้มเหลวการ resolve การอ้างอิงอ็อบเจ็กต์ ข้อผิดพลาดการเขียน ไฟล์ และการล้นของบัฟเฟอร์เอาต์พุต เอกสารในหน่วยความจำที่ถูกต้องไม่อาจ ถูก serialize เป็น byte stream ที่ถูกต้องได้ ข้อความระบุชื่อขั้นตอน
• Context getContext() คืน output_path (ว่างสำหรับเอาต์พุตแบบ string) และ writer_state (ขั้นตอน เช่น header, body, xref, trailer) getter แบบมีชนิด: getOutputPath(), getWriterState()
• Recovery การกระทำด้านโครงสร้างพื้นฐาน: ตรวจสอบพื้นที่ดิสก์ สิทธิ์ของไฟล์ และ output stream

PageLayoutException

• ถูกยกเมื่อใด เมื่อข้อจำกัดการจัดวางหน้าไม่อาจสนองได้: การละเมิด column-layout (ความกว้างไม่เพียงพอ จำนวน column ที่ไม่ถูกต้อง) เนื้อหา ที่ล้นเกินขอบเขตหน้า และความขัดแย้งของ margin การจัดวางที่ร้องขอเป็นไป ไม่ได้เชิงเรขาคณิตสำหรับมิติหน้าและเนื้อหาที่กำหนด ข้อความระบุชื่อหมายเลขหน้าเมื่อทราบและข้อจำกัดที่ถูกละเมิด
• Context getContext() คืน page_number (เริ่มจากหนึ่ง หรือ 0 หาก ไม่ทราบ) และ constraint getter แบบมีชนิด: getPageNumber(), getConstraint()
• Recovery การกระทำของนักพัฒนา: ปรับขนาดหน้า margin การตั้งค่า column หรือ เนื้อหา

TemplateException

• ถูกยกเมื่อใด เมื่อการนำเข้าหรือใช้ซ้ำ template ของ PDF ล้มเหลวใน TemplateManager: การเปลี่ยนสถานะ template ที่ไม่ถูกต้อง (การเริ่มหรือสิ้นสุด template นอกลำดับ) การอ้างอิง template ที่ไม่มีอยู่ และความล้มเหลว การบีบอัด stream ระหว่างการ serialize template ข้อความระบุชื่อ operation และ template id เมื่อกำหนดแล้ว
• Context getContext() คืน template_id (ว่างหากยังไม่กำหนด) และ operation (เช่น begin, end, use, serialize) getter แบบมีชนิด: getTemplateId(), getOperation()
• Recovery การกระทำของนักพัฒนา: แก้ลำดับการใช้ template หรือ source PDF

invariant ของสตรีมเนื้อหา

ContentStreamBalanceException

• ถูกยกเมื่อใด เมื่อ ContentStreamBuilder ตรวจพบคู่ operator ที่ไม่สมดุล ตอนปิด stream (หรือกลาง stream เมื่อ invariant ถูกยืนยันแบบ eager) มันจับตัวนับความลึกที่ล้มเหลว invariant ความสมดุลเพื่อให้ การล็อกระบุได้ว่า emitter ตัวใดทำ q, BT, หรือ BMC รั่วโดยไม่มี Q, ET, หรือ EMC ที่จับคู่ ตาม ISO 32000-2:2020 §8.4.2 (graphics-state stack), §9.4.1 (text objects), และ §14.6 (marked content)
• Context getContext() คืน graphics_depth, text_block_depth, marked_content_depth, และ offending_operator getter แบบมีชนิด: getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator()
• Recovery การกระทำของนักพัฒนา: ค้นหา emitter ที่เปิด construct โดยไม่ปิดมัน

GraphicsStateBalanceException

• ถูกยกเมื่อใด เมื่อ content stream ของ PDF ปิดด้วย operator q/Q ที่ ไม่สมดุล ISO 32000-2:2020 §8.4.2 กำหนดให้การบันทึก graphics-state (q) แต่ละครั้ง ต้องจับคู่กับการ restore (Q) หนึ่งครั้งพอดีก่อน stream สิ้นสุด ความไม่สมดุล ทำให้ transform, clipping path, สี และ rendering intent รั่วเข้าสู่หน้า ถัดไปหรือ Form XObject ถูกยกเฉพาะเมื่อเปิดการตรวจ graphics-state แบบ strict (NEXTPDF_GFXSTATE_STRICT=1) ในโหมด relaxed จะมีคำเตือนถูกปล่อยผ่าน trigger_error() แทน
• Context getContext() คืน save_depth (เป็นบวกเมื่อ save มากเกินไป เป็นลบเมื่อ restore มากเกินไป) getter แบบมีชนิด: getSaveDepth()
• Recovery การกระทำของนักพัฒนา: ค้นหาคู่ save()/restore() ที่ไม่จับคู่กัน

MissingShadingResourceException

• ถูกยกเมื่อใด เมื่อ ConicGradientRenderer::render() ถูกเรียกใช้ โดยไม่มีบริบท registry ของ Shading-resource การเปลี่ยนแปลงแบบ breaking ใน v10.0.0 ลบเส้นทาง surrogate แบบ implicit-marker-map เดิมออก: ผู้เรียกต้องสร้าง ตัวเรนเดอร์ด้วย ShadingResourceRegistryInterface เพื่อให้อ็อบเจ็กต์ indirect /ShadingType 4 ถูกลงทะเบียนกับ Shading-resource subdictionary ของหน้า (ISO 32000-2 §8.7.4.2 / §8.7.4.3) ข้อความระบุชื่อบริบทของผู้เรียก และชี้ไปยังหมายเหตุการ migration v9.x→v10.0
• Context getContext() คืน context (ป้ายบริบทของผู้เรียกสั้นๆ เช่น ConicGradientRenderer::render)
• Recovery การกระทำของผู้เรียกไลบรารี: เชื่อมต่ออินสแตนซ์ registry ของ Shading-resource เข้ากับ constructor ของตัวเรนเดอร์ก่อนเรียก render()

Linearization (Fast Web View)

LinearizationInvariantException

• ถูกยกเมื่อใด เมื่อ Linearizer แบบสามรอบ v2 ตรวจพบว่า การยืนยัน MEASURE → PLACE → FILL ของมันถูกละเมิด: จำนวนไบต์ใน Pass 3 ไม่ ตรงกับความยาวไฟล์ที่ Pass 1 ทำนายไว้ (offset drift) ตัวยึดตำแหน่ง dictionary ของ linearization เล็กเกินไปสำหรับความกว้างที่ serialize หรือ offset ของ hint-stream /H [offset length] ไม่ตรงกับเอาต์พุตสุดท้าย การปรากฏสิ่งนี้ แทนการปล่อย PDF ที่เสียหายเป็นการรับประกันความปลอดภัยที่ระบุไว้
• Context getContext() คืน invariant (ชื่อ invariant ที่ถูกละเมิด), expected, actual, และ delta (ผลต่างแบบมีเครื่องหมาย) getter แบบมีชนิด: getInvariant(), getExpectedValue(), getActualValue()
• Recovery การกระทำของผู้ดูแล: ยื่นรายงานข้อบกพร่อง — invariant เหล่านี้ควร เป็นจริงสำหรับ input ที่ดีทุกตัว จับ exception ก่อนหน้าที่เชื่อมโยงกันไว้

LinearizationUnimplementedException

• ถูกยกเมื่อใด เมื่อ feature flag ของ linearizer ถูกตั้งเป็น backend ที่ถูกปิดโดยเจตนา ปัจจุบันถูกยกเฉพาะสำหรับ linearizerVersion === 'v1-noop' ซึ่งเป็นการตั้งค่า downgrade ฉุกเฉินที่ปฏิเสธ ความพยายาม linearization ทั้งหมดขณะรันไทม์โดยไม่ต้องเปลี่ยนโค้ดหรือ redeploy — มีประโยชน์สำหรับ kill-switch Fast Web View ในการใช้งานจริง
• Context getContext() คืน reason (คำอธิบายสั้นๆ ที่มนุษย์ อ่านได้) getter แบบมีชนิด: getReason()
• Recovery การกระทำของผู้ปฏิบัติงาน / release-engineering: ปรับการกำหนดค่า หรืออัปเกรดเป็น backend เวอร์ชันที่แก้ไขแล้ว

ความสอดคล้องและ invariant ของโปรไฟล์

ConformanceViolationException

• ถูกยกเมื่อใด เมื่อคุณสมบัติที่ร้องขอไม่อาจปล่อยออกได้โดยไม่ ทำลายสัญญาความสอดคล้อง ISO ที่เอกสารประกาศไว้ และเอนจิน ล้มเหลวแบบปิดแทนการเขียนอ็อบเจ็กต์ที่ไม่สอดคล้อง ตัวกระตุ้นหลักคือ multimedia Screen annotation หรือ Rendition action (ISO 32000-2:2020 §12.5.6.18 / §13.2) ภายใต้ archival profile แบบ PDF/A ซึ่ง PDF/A ทุกส่วน ห้าม (ISO 19005 series) — ไฟล์จะล้มเหลวการตรวจสอบ veraPDF เอนจินจึงปฏิเสธ ตั้งแต่ต้น
• Context getContext() คืน conformance_mode (โหมดที่ประกาศ เช่น pdfa4) และ feature (คุณสมบัติที่ถูกปฏิเสธ เช่น Screen annotation) ทั้งสองเป็นพร็อพเพอร์ตี public readonly เหตุผลคือข้อความ exception
• Recovery การกระทำของนักพัฒนา: ลบการเรียก multimedia สำหรับเอาต์พุต archival หรือมุ่งไปยัง conformance profile ที่ไม่ใช่ archival (ค่าเริ่มต้น ConformanceMode::Plain)

PdfRViolationException

• ถูกยกเมื่อใด เมื่อ invariant ความสอดคล้อง PDF/R-1 (ISO 23504-1:2020) ถูกละเมิด ไม่ว่าจะที่การสร้าง value object (profile PdfRStrip, PdfRPage, PdfRDocument) หรือที่เวลา validator (PdfRValidator) มันจับ ข้อกำหนด normative ที่เป็นปัญหาและคำอธิบายการละเมิดหนึ่งบรรทัดเพื่อให้ผู้บริโภค audit สามารถส่งข้อค้นพบไปยัง sub-clause §6 ที่ถูกต้องโดยไม่ต้องแยกวิเคราะห์ข้อความ อิสระ
• Context getContext() คืน standard (เป็น ISO 23504-1:2020 เสมอ), clause (เส้นทาง clause เช่น 6.6.1) และ violation getter แบบมีชนิด: getClause(), getViolation()
• Recovery การกระทำของนักพัฒนา: แก้ input ที่ถูกปฏิเสธหรือสร้างเอกสารใหม่ ให้สอดคล้องกับ clause ที่อ้างถึง

การสร้างบาร์โค้ด

BarcodeException

• ถูกยกเมื่อใด เมื่อการสร้างบาร์โค้ดล้มเหลวเนื่องจากข้อมูลที่ไม่ถูกต้องหรือ ข้อผิดพลาดการ encode ในทุก symbology ที่รองรับ (Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode) และความล้มเหลวการเรนเดอร์ GD ระหว่างการสร้าง รูปภาพ ค่าบาร์โค้ดถูกจำกัดด้วยส่วนตัดทอนที่ 128 ไบต์ในข้อความและ context — payload ที่ยาวเกินหรือเป็นไบนารีจะถูกเก็บแบบตัดทอนพร้อม ตัวระบุ ... (<N> bytes, truncated) เพื่อไม่ให้คัดลอกทั้งหมดลงในล็อกได้
• Context getContext() คืน barcode_type (symbology เช่น QRCODE, EAN13, CODE128) และ value (ค่าที่ตัดทอน) getter แบบมีชนิด: getBarcodeType(), getValue()
• Recovery การกระทำของนักพัฒนา: แก้ข้อมูลบาร์โค้ดหรือการเลือก symbology

BarcodeEncoderNotFoundException

• ถูกยกเมื่อใด จาก BarcodeEncoderRegistry เมื่อชนิด encoder ที่ร้องขอ ไม่รู้จักหรือ capability gate ของมันปิดอยู่ มันยังนำ PSR-11 Psr\Container\NotFoundExceptionInterface ไปใช้ด้วย registry จึงเป็น คอนเทนเนอร์ที่สอดคล้องกับมาตรฐาน ข้อความระบุชื่อ symbology และ เหตุผล
• Context ไม่เขียนทับ getContext() จึงคืนอาร์เรย์ว่าง type และ reason เข้าถึงได้ผ่าน getter getType() และ getReason() และในข้อความ
• Recovery การกระทำของนักพัฒนา: ลงทะเบียน encoder หรือติดตั้งแพ็กเกจ ที่จัดหามัน (ตัวอย่างเช่น nextpdf/pro สำหรับ Micro QR / DotCode / HanXin / JabCode)

การเข้ารหัสลับ การเข้ารหัส และลายเซ็น

EncryptionException

• ถูกยกเมื่อใด เมื่อการเข้ารหัสลับหรือถอดรหัส PDF ล้มเหลว: ความล้มเหลว encrypt/decrypt ของ AES-256-CBC ข้อผิดพลาด OpenSSL ขนาด IV ที่ไม่ถูกต้อง ความล้มเหลว การคำนวณแฮช และข้อผิดพลาดการคำนวณค่า UE/OE โดยทั่วไปคือส่วนขยาย OpenSSL ที่ ขาดหายไปหรือกำหนดค่าผิด วัสดุคีย์ที่ไม่ถูกต้อง หรือข้อมูลที่เข้ารหัสลับเสียหาย ข้อความระบุชื่อ operation และอัลกอริทึม
• Context getContext() คืน algorithm (เช่น AES-256-CBC) และ operation (เช่น encrypt, decrypt, key_derivation) getter แบบมีชนิด: getAlgorithm(), getOperation()
• Recovery การกระทำด้านโครงสร้างพื้นฐาน: ตรวจสอบให้แน่ใจว่า OpenSSL พร้อมใช้งานและกำหนดค่า อย่างถูกต้อง ดูการเข้ารหัสลับและสิทธิ์

UnsupportedAlgorithmException

• ถูกยกเมื่อใด เมื่ออัลกอริทึมการเข้ารหัสลับไม่อาจรันได้ใน รันไทม์ปัจจุบัน: ส่วนขยาย PHP ที่จำเป็นไม่พร้อมใช้งาน ไลบรารีพื้นฐาน ขาด primitive ส่วนขยาย hash ที่มาด้วยไม่อาจสังเคราะห์ตัวแปร SHAKE/XOF หรืออัลกอริทึมไม่ได้ลงทะเบียนใน SignatureAlgorithmRegistry เอนจินต้องไม่ลดทอนลงเป็น primitive ที่อ่อนกว่า อย่างเงียบๆ จึงปรากฏสิ่งนี้แทน static factory nonFipsHostUnderFipsProfile() ยกมันขึ้น (พร้อมตัวระบุอัลกอริทึม regulatory-profile:fips) เมื่อเลือก RegulatoryProfile::FIPS แต่ไม่อาจ ยืนยัน provider OpenSSL ที่ผ่านการตรวจ FIPS ได้ (ทั้ง FIPS_ABSENT และ INDETERMINATE ล้มเหลวแบบปิด)
• Context getContext() คืน algorithm (ชื่อหรือ OID เช่น shake256, Ed25519, AES-256-GCM) และ reason (ที่ผู้ปฏิบัติงานทำตามได้) getter แบบมีชนิด: getAlgorithm(), getReason()
• Recovery การกระทำของผู้ปฏิบัติงาน: ติดตั้งส่วนขยายที่ขาดหายไปหรืออัปเกรด รันไทม์ สำหรับ FIPS gate ให้ติดตั้งบิลด์ OpenSSL ที่ผ่านการตรวจ FIPS หรือตั้ง NEXTPDF_FIPS_MODE อย่างชัดเจน การกระทำของนักพัฒนา: ลงทะเบียน descriptor อัลกอริทึมแบบกำหนดเองผ่าน SignatureAlgorithmRegistry::register()

SignatureException

• ถูกยกเมื่อใด เมื่อ operation ลายเซ็นดิจิทัลล้มเหลว: การจัดการใบรับรอง และคีย์ส่วนตัว (การแยกวิเคราะห์ PKCS#12 การถอดรหัส PEM/DER การตรวจสอบ X.509), การสร้าง PKCS#7/CMS รูปแบบลายเซ็น ECDSA การละเมิดขนาดคอนเทนเนอร์ การ encode DER และการ orchestrate PAdES ข้อผิดพลาดเฉพาะ TSA จะถูกรายงานโดย TsaException ที่เฉพาะเจาะจงกว่าแทน ให้เลือก factory ที่ระบุชื่อแบบมีชนิด มากกว่า constructor แบบเรียงลำดับ แต่ละตัวผูกสาเหตุรากเข้ากับ ส่วนท้ายของข้อความ ตัวอย่าง: ltvCapabilityMissing() (B-LT/B-LTA ต้องใช้ nextpdf/enterprise), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed() ตระกูล Ed25519 (ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing(), และคู่สถานะ OCSP nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (RFC 6960 §4.2.1) factory เหล่านี้ล้มเหลวแบบปิดแทนการปล่อยลายเซ็นที่ถูกลดระดับ อย่างเงียบๆ
• Context getContext() คืน cert_info (subject DN หรือ thumbprint หรือ ว่าง), signature_level (ระดับ PAdES ที่พยายาม เช่น B-B, B-T, B-LT, B-LTA) และ detail (การวินิจฉัยที่ทำตามได้ ว่างสำหรับ constructor แบบเรียงลำดับเดิม) getter แบบมีชนิด: getCertInfo(), getSignatureLevel(), getDetail()
• Recovery การกระทำของนักพัฒนา: แก้การกำหนดค่าใบรับรอง/คีย์ สำหรับ factory ที่ขาดความสามารถ ให้ติดตั้งแพ็กเกจที่ระบุชื่อ ดู Signature and timestamp failures สำหรับรายการอาการและการแก้ไขแยกตาม factory

BlackPointCompensationUnsupportedException

• ถูกยกเมื่อใด จาก NullBlackPointCompensationTransform::transform() เมื่อผู้เรียกขอให้ null adapter ใช้ transform black-point compensation ของ ISO 18619 ที่ไม่ใช่ Default null adapter เป็น fallback ที่ปลอดภัยสำหรับ สภาพแวดล้อมที่ไม่มี backend จัดการสี การสร้างตัวอย่างที่ transform แล้วโดยไม่มีโมดูลจัดการสีจริงจะรายงานการแปลงผิด อย่างเงียบๆ ไม่เหมือนรายการส่วนใหญ่ที่นี่ ตัวนี้สืบทอดจาก \RuntimeException โดยตรง ไม่ใช่ NextPdfException เส้นทาง catch (\RuntimeException) ที่มีอยู่ จึงยังทำงานต่อไป
• Context ไม่มี getContext() มันเป็น \RuntimeException ธรรมดา รายละเอียด อยู่ในข้อความ
• Recovery การกระทำของนักพัฒนา: ลงทะเบียน BlackPointCompensationTransform จริง (LittleCMS, Argyll, pure-PHP) หรือจำกัด /UseBlackPtComp ไว้ที่ BlackPointCompensation::Default

การประกอบเอกสารและการเข้าถึง

UnsupportedSourceDocumentException

• ถูกยกเมื่อใด เมื่อเอกสารต้นทางไม่อาจคัดลอกอย่างปลอดภัยเข้าสู่ เอาต์พุต merge/split และ operation ล้มเหลวแบบปิดแทนการปล่อยผลลัพธ์ที่ เสียหายหรือถูกบุกรุกด้านความปลอดภัย ใช้ factory ที่ระบุชื่อ: encrypted() (ISO 32000-2 §7.6 — เนื้อหาไม่อาจคัดลอกได้โดยไม่มีคีย์) signed() (§12.8 — การคัดลอกหน้าจะทำให้ลายเซ็น byte range เป็นโมฆะ), unsupportedStreamFilter() (filter ที่ตัวอ่าน object-graph ไม่อาจ round-trip ได้), multipleInteractiveForms() (ข้อจำกัดที่บันทึกไว้: ต้นทาง มากกว่าหนึ่งพกพา /AcroForm ที่ไม่ว่าง §12.7) และ splitWithInteractiveForm() (ข้อจำกัดที่บันทึกไว้: การ subset หน้าจาก ต้นทางที่มี form จะทิ้ง widget ให้ไร้ที่พึ่ง) สืบทอดจาก \RuntimeException โดยตรง ไม่ใช่ NextPdfException
• Context ไม่มี getContext() มันเป็น \RuntimeException ธรรมดา สาเหตุ และหมายเลขอ็อบเจ็กต์ที่ได้รับผลกระทบถูกระบุชื่อในข้อความ
• Recovery การกระทำของนักพัฒนา: ถอดรหัสต้นทางก่อนหรือจัดหาคีย์ สำหรับต้นทางที่เซ็นแล้ว ให้เซ็นหลังการรวมแทน สำหรับการรวมหลาย form ให้ flatten หรือลบฟิลด์ form ของทุกต้นทางยกเว้นหนึ่ง สำหรับการ split ที่มี form ให้ flatten form ก่อนการ split

InvalidBcp47TagException

• ถูกยกเมื่อใด จาก Bcp47Validator::validate() เมื่อ candidate language tag มีรูปแบบไม่ถูกต้องตาม RFC 5646 §2.1 ABNF หรือล้มเหลวการค้นหา ใน registry ที่คัดเลือกไว้ เฉพาะเจาะจงกับโดเมน BCP-47 / ISO 14289-2:2024 §8.4.4 แยกจาก InvalidConfigException เพื่อให้ผู้เรียกที่อยู่ปลายน้ำของ seam การช่วยการเข้าถึง จับชนิดที่แคบได้ คู่ predicate Bcp47Validator::isWellFormed() / isValid() ยังคงเป็นพื้นผิวค่าคืนแบบ backward-compatible สำหรับผู้เรียกที่ชอบการแยกกิ่งมากกว่า exception
• Context getContext() คืน tag (candidate ตามที่ป้อนมาทุกประการ) และ reason (รหัสการปฏิเสธที่เครื่องอ่านได้และเสถียร เช่น empty-string, well-formed-shape, unregistered-primary, duplicate-variant) getter แบบมีชนิด: getTag(), getReason()
• Recovery การกระทำของนักพัฒนา: แก้ language tag ให้เป็น BCP-47 tag ที่มีรูปแบบ ถูกต้องและลงทะเบียนแล้ว ดู Fonts and tagging

FormFieldAccessibilityException

• ถูกยกเมื่อใด เมื่อฟิลด์ form แบบโต้ตอบต้องพึ่งพาชื่อที่ เข้าถึงได้แบบสังเคราะห์ (ไม่ได้มาจากผู้เขียน) ขณะสร้างเอกสาร PDF/UA ที่ เปิดการบังคับใช้ชื่อฟิลด์ที่เข้าถึงได้แบบ strict เอาต์พุต PDF/UA เริ่มต้นปล่อย ชื่อ fallback แบบสังเคราะห์ลงใน widget /Contents เพื่อให้ฟิลด์ไม่เคย ไม่มีชื่อ ส่วนโหมด strict กำหนดให้ผู้เขียนจัดหาชื่อที่มีความหมาย (tooltip หรือคำบรรยายสำหรับ push button ที่ไม่มี action) เพื่อให้ผู้ใช้ screen-reader ได้รับคำอธิบายจริง (ISO 14289-2:2024 §8.10.2)
• Context ไม่เขียนทับ getContext() จึงคืนอาร์เรย์ว่าง $fieldId เป็นพร็อพเพอร์ตี public readonly เหตุผลคือข้อความ
• Recovery การกระทำของนักพัฒนา: จัดหา tooltip / ชื่อที่เข้าถึงได้สำหรับ ฟิลด์ที่ระบุชื่อก่อนสร้างเอกสาร PDF/UA แบบ strict หรือปิดโหมด strict ดู PDF/A and PDF/UA validation

VendorExtensionRegistryConflictException

• ถูกยกเมื่อใด จาก VendorExtensionRegistry::register() เมื่อผู้เรียก ลงทะเบียน prefix ของ vendor developer-extension PDF ที่รู้จัก (ISO 32000-2:2020 §7.12.1) ซ้ำด้วยคำอธิบายที่ขัดแย้งกับ ข้อมูลเมตาที่ลงทะเบียนไว้แล้ว descriptor เป็นแบบ append-only และตรวจจับความขัดแย้ง exception แบบมีชนิดแทนที่ \RuntimeException ทั่วไปเพื่อให้ผู้เรียกจับ คลาสที่เฉพาะเจาะจงนี้ได้
• Context getContext() คืน prefix, existing_description, และ attempted_description getter แบบมีชนิด: getPrefix(), getExistingDescription(), getAttemptedDescription()
• Recovery การกระทำของนักพัฒนา: ลงทะเบียน prefix ด้วยคำอธิบายที่ มีอยู่ หรือใช้ prefix ที่แตกต่าง อย่าเขียนทับข้อมูลเมตาที่ลงทะเบียนไว้

การส่งออกข้อมูลการตรวจสอบ

AuditExportException

• ถูกยกเมื่อใด เมื่อการประกอบ bundle audit-export การสร้าง traceability-matrix หรือการ project schema ล้มเหลวขณะรันไทม์ ครอบคลุม I/O กับ claims.json / manifest.json การ encode/decode JSON ของ bundle ตามแบบ และความไม่ตรงกันของ schema-version บนเส้นทาง backward-compat AuditExporter::projectToV1() ข้อความระบุชื่อขั้นตอน artefact เมื่อทราบ และ รายละเอียด
• Context getContext() คืน stage (เช่น read_claims, encode_bundle, project_v1), detail, และ artefact (path หรือ schema_version ที่ทำให้เกิดความล้มเหลว) getter แบบมีชนิด: getStage(), getDetail(), getArtefact()
• Recovery การกระทำด้าน compliance / DevOps: ตรวจสอบ path ของ input artefact สร้าง claims.json ใหม่จากการรันที่สะอาด หรือสร้าง manifest ใหม่ก่อน ลองทำการ export อีกครั้ง

value object ของการละเมิด

สิ่งเหล่านี้ไม่ใช่ exception เป็น value object แบบ immutable ที่เอนจินคืนมาเพื่อ อธิบายการละเมิดแต่ละรายการ มันไม่พกพา getContext()

ComplianceViolation

• มันคืออะไร value object แบบ final readonly ที่แทนความล้มเหลวของกฎหนึ่งข้อ ที่รายงานโดย validator ภายนอก (veraPDF หรือเทียบเท่า) รวมถึงการอ้างอิง ISO clause และตำแหน่งภายในโครงสร้าง PDF
• Fields พร็อพเพอร์ตี public readonly: ruleId (ตัวระบุกฎของ validator เช่น 6.1.2-1), clause (การอ้างอิง ISO clause เช่น ISO 19005-1:2005, 6.1.2), severity (เช่น error, warning), location (เส้นทางอ็อบเจ็กต์ภายในโครงสร้าง PDF) และ message (คำอธิบายที่มนุษย์อ่านได้)
• Use ตรวจสอบคอลเลกชันที่ compliance validator คืนมา ส่งหรือ แสดงแต่ละรายการตาม severity และ clause ดู PDF/A and PDF/UA validation

RuleViolation

• มันคืออะไร value object แบบ final readonly ที่แทนการละเมิด business-rule Schematron / EN 16931 หนึ่งข้อ คืนโดย SchematronRunnerInterface::runRules() และรวมไว้ใน ValidationResult::$ruleViolations ความเสถียรเป็นแบบ experimental
• Fields พร็อพเพอร์ตี public readonly: ruleId (ตัวระบุ EN 16931 เช่น BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n} หรือ pack เฉพาะ tier), severity (enum RuleSeverity), message (ข้อความกฎ en-GB), xpath (XPath เข้าสู่ XML ที่ฝังไว้ null สำหรับกฎทั้งเอกสาร) และ semanticPath (เส้นทาง BG/BT แบบ dot-notation เช่น BG-22.BT-106 null สำหรับ การละเมิดเชิงโครงสร้าง)
• Use ตรวจสอบคอลเลกชันบนผลการตรวจสอบ ส่งหรือแสดงแต่ละ รายการตาม severity, ruleId, และตัวระบุตำแหน่ง

ดูเพิ่มเติม

• Error reference index
• Knowledge base index
• Signature and timestamp failures
• Encryption and permissions
• Fonts and tagging
• PDF/A and PDF/UA validation