Lỗi core và lỗi chung

Phạm vi

Các mục này bao quát các ngoại lệ core và lỗi đa dụng mà NextPDF nêu ra. Hầu hết mở rộng lớp cơ sở NextPdfException, vốn tự nó mở rộng \RuntimeException và hiện thực ContextAwareExceptionInterface. Giao diện đó phơi bày một phương thức, getContext(): array, trả về một bản đồ phẳng dạng snake_case gồm các giá trị nguyên thủy an toàn để tuần tự hóa vào nhật ký hoặc payload APM.

Bắt họ lớp NextPdfException chỉ với một catch (NextPdfException $e). Thêm một catch (\RuntimeException $e) để bao quát số ít lỗi cấp thấp trong tập này vốn mở rộng trực tiếp \RuntimeException (liệt kê bên dưới). Lớp cơ sở NextPdfException::getContext() trả về một mảng rỗng; các lớp con ghi đè nó để thêm trường theo lĩnh vực. Khi một lớp không ghi đè getContext(), nó kế thừa mảng rỗng và chi tiết chẩn đoán nằm trong thông báo và các getter có kiểu thay thế.

Bốn kiểu trong tập này không mở rộng NextPdfException: BlackPointCompensationUnsupportedException và UnsupportedSourceDocumentException mở rộng trực tiếp \RuntimeException (bắt chúng dưới dạng \RuntimeException), còn ComplianceViolation và RuleViolation là các đối tượng giá trị, không phải ngoại lệ — chúng được lập tài liệu ở đây vì chúng mô hình hóa dữ liệu lỗi và vi phạm mà engine trả về.

Ngoại lệ cơ sở

NextPdfException

• Nó là gì. Lớp cơ sở abstract cho họ ngoại lệ chính của NextPDF trải khắp core và các gói mở rộng của nó. Nó mở rộng \RuntimeException và hiện thực ContextAwareExceptionInterface. Bắt một kiểu duy nhất này sẽ chặn họ lớp NextPdfException; số ít lỗi mở rộng trực tiếp \RuntimeException (liệt kê bên trên) còn cần thêm một lần bắt \RuntimeException nữa.
• Context. getContext() cơ sở trả về một mảng rỗng. Các lớp con ghi đè nó để trả về các trường theo lĩnh vực cụ thể.
• Khôi phục. Không ném trực tiếp. Hãy dùng nó làm kiểu bắt-tất-cả; rẽ nhánh theo lớp con cụ thể để xử lý chuyên biệt.

Cấu hình và mở khóa tính năng

InvalidConfigException

• Khi nào nó được ném. Khi một giá trị Config hoặc một tổ hợp giá trị không hợp lệ — thiếu một thiết lập bắt buộc, một tùy chọn loại trừ lẫn nhau, hoặc một giá trị nằm ngoài phạm vi được chấp nhận. Đây là tín hiệu của lỗi nhà phát triển: mã gọi đã cung cấp một cấu hình cần được sửa trước khi thử lại. Thông báo nêu khóa, kiểu hoặc phạm vi mong đợi, và kiểu debug thực tế của giá trị được cung cấp.
• Context. getContext() trả về config_key, given_value, và expected_type. Các getter có kiểu: getConfigKey(), getGivenValue(), getExpectedType().
• Khôi phục. Hành động của nhà phát triển: sửa khóa cấu hình được nêu thành một giá trị có kiểu hoặc phạm vi mong đợi trước khi gọi NextPDF lần nữa.

NotImplementedException

• Khi nào nó được ném. Khi một điểm vào API công khai được đạt tới nhưng bản hiện thực của nó được cố ý vắng mặt trong bản phát hành hiện tại. Dùng cho các shim bị phế bỏ tồn tại nhằm trả về cho các caller tiền-bisect một lỗi lớn tiếng, có thể hành động được thay vì một no-op âm thầm. Thông báo kết hợp một nhãn feature có thể grep được bằng máy và một tham chiếu followUp (ID lỗi, neo theo dõi, hoặc tên sprint).
• Context. Không ghi đè getContext(), nên nó trả về một mảng rỗng. Các giá trị $feature và $followUp là các thuộc tính công khai chỉ đọc và được nhúng trong thông báo.
• Khôi phục. Hành động của caller thư viện: gỡ bỏ lời gọi, hoặc ghim vào một bản phát hành tương lai có triển khai phần follow-up được nêu tên.

IncompatibleFeatureFlagsException

• Khi nào nó được ném. Tại thời điểm dựng Config (Config::validate()) khi một tổ hợp CssFeatureFlags không nhất quán nội tại — một cờ giả định trước một cờ khác đang bị tắt. Tổ hợp bị cấm duy nhất hiện nay là layoutSubgrid = true với layoutGrid = false: một trục được subgrid suy ra các đường lưới của nó từ một grid container cha (CSS Grid Layout Module Level 2 §1), nên subgrid mà không có grid mô tả một lưới không thể tồn tại. Kiểm tra này chạy trên các cờ đã được phân giải, nên CssRenderingMode::Safe (vốn ép buộc mọi tính năng Phase 4+ tắt) che lấp tổ hợp này thay vì kích hoạt nó. Mở rộng StrictModeViolation.
• Context. getContext() hợp nhất các trường chế độ nghiêm ngặt của lớp cha (cssDeviation, excId, chunkSha256, location) với các boolean layoutGrid và layoutSubgrid. location là Config::validate() và cssDeviation mã hóa cặp cờ.
• Khôi phục. Hành động của caller thư viện: bật layoutGrid cùng với layoutSubgrid, hoặc tắt layoutSubgrid.

IncompatibleRenderingModeException

• Khi nào nó được ném. Tại thời điểm dựng Config khi một cặp CssRenderingMode và CssLayoutMode nằm ngoài các ô tương thích của ma trận chế độ. Cặp bị cấm duy nhất hiện nay là CssRenderingMode::Safe + CssLayoutMode::Retained — Safe ép buộc mọi tính năng Phase 4+ tắt, để lại các formatting context của chế độ retained (Grid, Subgrid, @container) không có bên tiêu thụ, nên tổ hợp này bị từ chối thay vì để nó suy giảm âm thầm. Mở rộng StrictModeViolation.
• Context. getContext() hợp nhất các trường chế độ nghiêm ngặt của lớp cha với mode1 (giá trị rendering-mode) và mode2 (giá trị layout-mode). Trường cssDeviation mã hóa cặp chế độ; location là Config::validate().
• Khôi phục. Hành động của caller thư viện: chọn Safe + Streaming để rollback, hoặc một chế độ kết xuất không phải Safe (Normal / Strict / Audit) với Retained cho Grid / Subgrid / Container Queries.

StrictModeViolation

• Khi nào nó được ném. Lớp cơ sở abstract cho mọi ngoại lệ lệch-khỏi-spec được ném dưới CssRenderingMode::Strict. Ở chế độ nghiêm ngặt, bất kỳ độ lệch CSS nào được phát hiện mà không liên kết với một mục ngoại lệ EXC-NNN đã đăng ký đều ném ra một thể hiện của lớp này (hoặc một lớp con) tại điểm phát hiện. Không ném trực tiếp; xem IncompatibleFeatureFlagsException và IncompatibleRenderingModeException.
• Context. getContext() trả về bốn trường ADR-023: cssDeviation (nhãn ngắn cho cấu trúc lệch), excId (định danh registry khi đã đăng ký, ngược lại null), chunkSha256 (hash chunk trích dẫn spec khi biết, ngược lại null), và location (nguồn gốc dễ đọc cho caller, ngược lại null).
• Khôi phục. Hành động của caller thư viện: đăng ký độ lệch này như một mục EXC-NNN mới đã được phê duyệt, hoặc sửa trình kết xuất để loại bỏ độ lệch.

Đầu vào HTML và CSS

HtmlParsingException

• Khi nào nó được ném. Khi phân tích đầu vào HTML hoặc dựng DOM thất bại: khai báo charset không hợp lệ, vi phạm giới hạn kích thước đầu vào, độ lồng ghép vượt mức, tràn số lượng phần tử, và lỗi cấu trúc bảng như số hàng tối đa. Việc cạn kiệt tài nguyên riêng cho CSS được báo cáo thay thế bởi CssParserLimitExceededException và CssResolutionBudgetExceededException.
• Context. getContext() trả về html_snippet (một đoạn trích ngắn, bị cắt của phần HTML gây lỗi), position (offset theo byte, hoặc -1 nếu không rõ), và rule (ràng buộc parser bị vi phạm). Các getter có kiểu: getHtmlSnippet(), getPosition(), getRule().
• Khôi phục. Hành động của nhà phát triển: đơn giản hóa đầu vào HTML hoặc điều chỉnh các giới hạn của parser.

CssParserLimitExceededException

• Khi nào nó được ném. Khi đầu vào CSS vượt quá một giới hạn an toàn của parser được cấu hình. Hai loại được bao quát qua các constructor có tên: forByteLimit() (stylesheet quá lớn để xử lý regex an toàn) và forNestingDepth() (đệ quy lồng CSS quá sâu). Cả hai thông báo đều nêu tên giá trị thực tế và giới hạn.
• Context. getContext() trả về limit_type (byte hoặc nesting_depth), actual, và limit.
• Khôi phục. Hành động của nhà phát triển: tách stylesheet thành các tệp nhỏ hơn, hoặc giảm độ sâu lồng ghép, hoặc nâng giới hạn được cấu hình.

CssResolutionBudgetExceededException

• Khi nào nó được ném. Khi việc phân giải :has() của CSS vượt quá ngân sách duyệt của nó. Trình phân giải :has() hai lượt áp dụng một ngân sách thăm-nút nghiêm ngặt để ngăn các bộ chọn bệnh lý gây ra các lượt duyệt tài liệu bậc hai; một khi tổng số lần thăm vượt quá giới hạn, stylesheet bị từ chối vì quá phức tạp. Thông báo nêu tên số lần thăm và ngân sách.
• Context. getContext() trả về visits và budget. Các getter có kiểu: getVisits(), getBudget().
• Khôi phục. Hành động của nhà phát triển: giảm độ phức tạp của bộ chọn, hoặc nâng ngân sách được cấu hình.

Phông chữ và ảnh

FontNotFoundException

• Khi nào nó được ném. Khi không thể định vị hoặc đọc một tệp phông chữ ở mức hệ thống tệp: họ phông chữ hoặc đường dẫn được yêu cầu không tồn tại, không đọc được, hoặc thư mục phông chữ được cấu hình không truy cập được. Dữ liệu phông chữ có thể hợp lệ — điều này chỉ báo hiệu rằng không thể với tới nó. Thông báo liệt kê các đường dẫn đã tìm.
• Context. getContext() trả về font_name, search_paths (một danh sách), và fallback_attempted (một bool). Các getter có kiểu: getFontName(), getSearchPaths(), wasFallbackAttempted().
• Khôi phục. Hành động của nhà phát triển: kiểm tra đường dẫn phông chữ. Hành động hạ tầng: sửa quyền tệp trên tệp hoặc thư mục phông chữ.

FontParsingException

• Khi nào nó được ném. Khi tìm thấy một tệp phông chữ nhưng nội dung của nó không dùng được: nó hỏng, ở định dạng không được hỗ trợ, hoặc thiếu các bảng bắt buộc. Bao quát các lỗi xác thực cấu trúc trong khi phân tích TrueType, Type 1, CFF, và OpenType — header bị cắt cụt, mục lục bảng không hợp lệ, thiếu các bảng bắt buộc (head, hhea, OS/2), lỗi giải nén, và vi phạm kích thước. Thông báo nêu tên tệp và lỗi phân tích.
• Context. getContext() trả về font_file và parse_error. Các getter có kiểu: getFontFile(), getParseError().
• Khôi phục. Hành động của nhà phát triển: thay tệp phông chữ bằng một tệp hợp lệ.

ImageProcessingException

• Khi nào nó được ném. Khi không thể giải mã một ảnh, ảnh ở định dạng không được hỗ trợ, hoặc xử lý GD/Imagick thất bại: magic byte không nhận diện được, dữ liệu JPEG hỏng, kiểu MIME không hỗ trợ, vi phạm giới hạn kích thước tệp, và lỗi cấp phát tài nguyên GD. Ảnh truy cập được nhưng không thể trích xuất dữ liệu pixel của nó để nhúng.
• Context. getContext() trả về image_path (rỗng đối với dữ liệu inline), format (được phát hiện hoặc mong đợi, ví dụ jpeg, png, unknown), và operation (ví dụ decode, resize, embed). Các getter có kiểu: getImagePath(), getFormat(), getOperation().
• Khôi phục. Hành động của nhà phát triển: cung cấp một tệp ảnh hợp lệ, được hỗ trợ.

Đầu ra, bố cục, và tuần tự hóa

CompressionException

• Khi nào nó được ném. Khi nén hoặc giải nén FlateDecode (zlib) thất bại — lỗi gzcompress/gzuncompress trên các content stream, dữ liệu phông chữ, nội dung trang, dữ liệu tệp đính kèm, và cross-reference stream. Thường là một input stream hỏng, không đủ bộ nhớ, hoặc thiếu tiện ích mở rộng zlib.
• Context. getContext() trả về algorithm (tên filter, ví dụ FlateDecode, LZWDecode) và stream_length (độ dài byte, hoặc -1 nếu không rõ). Các getter có kiểu: getAlgorithm(), getStreamLength().
• Khôi phục. Hành động hạ tầng: kiểm tra ext-zlib đã được nạp và bộ nhớ đủ.

WriterException

• Khi nào nó được ném. Khi tuần tự hóa PDF, linear hóa, hoặc xuất I/O thất bại: lỗi ghi stream của PdfWriter, hỏng bảng cross-reference, lỗi tạo header/trailer, lỗi phân giải tham chiếu đối tượng, lỗi ghi tệp, và tràn output buffer. Một tài liệu hợp lệ trong bộ nhớ không thể được tuần tự hóa thành một byte stream hợp lệ. Thông báo nêu tên giai đoạn.
• Context. getContext() trả về output_path (rỗng đối với output dạng chuỗi) và writer_state (giai đoạn, ví dụ header, body, xref, trailer). Các getter có kiểu: getOutputPath(), getWriterState().
• Khôi phục. Hành động hạ tầng: kiểm tra dung lượng đĩa, quyền tệp, và output stream.

PageLayoutException

• Khi nào nó được ném. Khi không thể thỏa mãn các ràng buộc bố cục trang: vi phạm bố cục cột (chiều rộng không đủ, số cột không hợp lệ), nội dung tràn ra ngoài ranh giới trang, và xung đột lề. Bố cục được yêu cầu là bất khả thi về mặt hình học đối với kích thước trang và nội dung đã cho. Thông báo nêu tên số trang khi biết và ràng buộc bị vi phạm.
• Context. getContext() trả về page_number (đánh số từ 1, hoặc 0 nếu không rõ) và constraint. Các getter có kiểu: getPageNumber(), getConstraint().
• Khôi phục. Hành động của nhà phát triển: điều chỉnh kích thước trang, lề, thiết lập cột, hoặc nội dung.

TemplateException

• Khi nào nó được ném. Khi một thao tác nhập hoặc tái sử dụng template PDF thất bại trong TemplateManager: chuyển trạng thái template không hợp lệ (bắt đầu hoặc kết thúc template ngoài thứ tự), tham chiếu một template không tồn tại, và lỗi nén stream trong khi tuần tự hóa template. Thông báo nêu tên thao tác và id của template khi đã được gán.
• Context. getContext() trả về template_id (rỗng nếu chưa được gán) và operation (ví dụ begin, end, use, serialize). Các getter có kiểu: getTemplateId(), getOperation().
• Khôi phục. Hành động của nhà phát triển: sửa trình tự sử dụng template hoặc PDF nguồn.

Bất biến của content stream

ContentStreamBalanceException

• Khi nào nó được ném. Khi một ContentStreamBuilder phát hiện một cặp toán tử mất cân bằng khi đóng stream (hoặc giữa stream khi các bất biến được khẳng định ngay). Nó ghi lại các bộ đếm độ sâu đã làm hỏng bất biến cân bằng nên việc ghi nhật ký có thể xác định emitter nào để lọt một q, BT, hoặc BMC mà không có Q, ET, hoặc EMC tương ứng. Theo ISO 32000-2:2020 §8.4.2 (graphics-state stack), §9.4.1 (text objects), và §14.6 (marked content).
• Context. getContext() trả về graphics_depth, text_block_depth, marked_content_depth, và offending_operator. Các getter có kiểu: getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator().
• Khôi phục. Hành động của nhà phát triển: định vị emitter đã mở một cấu trúc mà không đóng nó.

GraphicsStateBalanceException

• Khi nào nó được ném. Khi một content stream của PDF đóng với các toán tử q/Q mất cân bằng. ISO 32000-2:2020 §8.4.2 yêu cầu mỗi lần lưu graphics-state (q) phải được khớp đúng một lần khôi phục (Q) trước khi stream kết thúc; mất cân bằng để lọt transform, đường clipping, màu sắc, và rendering intent sang các trang hoặc Form XObject tiếp theo. Chỉ nêu ra khi bật kiểm tra graphics-state nghiêm ngặt (NEXTPDF_GFXSTATE_STRICT=1); ở chế độ nới lỏng, một cảnh báo được phát qua trigger_error() thay thế.
• Context. getContext() trả về save_depth (dương khi có quá nhiều lần lưu, âm khi có quá nhiều lần khôi phục). Getter có kiểu: getSaveDepth().
• Khôi phục. Hành động của nhà phát triển: định vị cặp save()/restore() không khớp.

MissingShadingResourceException

• Khi nào nó được ném. Khi ConicGradientRenderer::render() được gọi mà không có context registry tài nguyên Shading. Thay đổi gây phá vỡ ở v10.0.0 đã loại bỏ đường surrogate implicit-marker-map trước đó: caller phải dựng trình kết xuất với một ShadingResourceRegistryInterface để đối tượng gián tiếp /ShadingType 4 được đăng ký vào tiểu từ điển tài nguyên Shading của trang (ISO 32000-2 §8.7.4.2 / §8.7.4.3). Thông báo nêu tên context của caller và chỉ tới ghi chú di trú v9.x→v10.0.
• Context. getContext() trả về context (một nhãn ngắn về context của caller, ví dụ ConicGradientRenderer::render).
• Khôi phục. Hành động của caller thư viện: đấu nối một thể hiện registry tài nguyên Shading vào constructor của trình kết xuất trước khi gọi render().

Linear hóa (Fast Web View)

LinearizationInvariantException

• Khi nào nó được ném. Khi Linearizer ba lượt v2 phát hiện rằng các khẳng định MEASURE → PLACE → FILL của nó bị vi phạm: một số đếm byte ở Pass 3 không khớp với độ dài tệp dự đoán ở Pass 1 (lệch offset), một placeholder của từ điển linear hóa quá nhỏ so với chiều rộng đã tuần tự hóa, hoặc một offset của hint-stream /H [offset length] không khớp với output cuối. Phơi bày điều này thay vì phát ra một PDF bị hỏng là một bảo đảm an toàn được công bố.
• Context. getContext() trả về invariant (tên bất biến bị vi phạm), expected, actual, và delta (hiệu số có dấu). Các getter có kiểu: getInvariant(), getExpectedValue(), getActualValue().
• Khôi phục. Hành động của người bảo trì: gửi một báo cáo lỗi — các bất biến này nên giữ đúng với mọi đầu vào hợp khuôn. Ghi lại ngoại lệ trước đó trong chuỗi.

LinearizationUnimplementedException

• Khi nào nó được ném. Khi cờ tính năng của trình linear hóa được đặt thành một backend bị cố ý tắt. Hiện chỉ nêu ra cho linearizerVersion === 'v1-noop', thiết lập hạ-cấp-khẩn-cấp vốn từ chối mọi nỗ lực linear hóa tại môi trường chạy mà không cần thay đổi mã hay tái triển khai — hữu ích để kill-switch Fast Web View trong sản xuất.
• Context. getContext() trả về reason (một giải thích ngắn dễ đọc cho con người). Getter có kiểu: getReason().
• Khôi phục. Hành động của người vận hành / kỹ thuật phát hành: điều chỉnh cấu hình hoặc nâng cấp lên một phiên bản backend đã sửa.

Bất biến của profile và tuân thủ

ConformanceViolationException

• Khi nào nó được ném. Khi một tính năng được yêu cầu không thể phát ra mà không phá vỡ hợp đồng tuân thủ ISO đã khai báo của tài liệu, và engine thất bại theo hướng đóng thay vì ghi ra một đối tượng không tuân thủ. Trigger điển hình là một annotation Screen đa phương tiện hoặc một action Rendition (ISO 32000-2:2020 §12.5.6.18 / §13.2) dưới một profile lưu trữ PDF/A, vốn bị mọi phần của PDF/A cấm (loạt ISO 19005) — tệp sẽ không vượt qua xác thực veraPDF, nên engine từ chối ngay từ đầu.
• Context. getContext() trả về conformance_mode (chế độ đã khai báo, ví dụ pdfa4) và feature (tính năng bị từ chối, ví dụ Screen annotation). Cả hai đều là thuộc tính công khai chỉ đọc. Lý do nằm trong thông báo của ngoại lệ.
• Khôi phục. Hành động của nhà phát triển: bỏ lời gọi đa phương tiện cho output lưu trữ, hoặc nhắm tới một profile tuân thủ không phải lưu trữ (mặc định ConformanceMode::Plain).

PdfRViolationException

• Khi nào nó được ném. Khi một bất biến tuân thủ PDF/R-1 (ISO 23504-1:2020) bị vi phạm, hoặc tại lúc dựng đối tượng giá trị (các profile PdfRStrip, PdfRPage, PdfRDocument) hoặc tại lúc validator (PdfRValidator). Nó ghi lại điều khoản chuẩn tắc bị vi phạm và một mô tả vi phạm một dòng nên bên tiêu thụ audit có thể định tuyến phát hiện tới đúng tiểu điều khoản §6 mà không cần phân tích văn bản tự do.
• Context. getContext() trả về standard (luôn là ISO 23504-1:2020), clause (đường dẫn điều khoản, ví dụ 6.6.1), và violation. Các getter có kiểu: getClause(), getViolation().
• Khôi phục. Hành động của nhà phát triển: sửa đầu vào bị từ chối hoặc dựng lại tài liệu để tuân thủ điều khoản được trích dẫn.

Tạo mã vạch

BarcodeException

• Khi nào nó được ném. Khi tạo mã vạch thất bại do dữ liệu không hợp lệ hoặc lỗi mã hóa trên mọi hệ ký hiệu được hỗ trợ (Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode), và lỗi kết xuất GD trong khi tạo ảnh. Giá trị mã vạch bị giới hạn trích đoạn ở 128 byte trong thông báo và context — payload quá dài hoặc nhị phân được lưu dạng cắt cụt với một dấu ... (<N> bytes, truncated) để không thể sao chép nguyên vẹn vào nhật ký.
• Context. getContext() trả về barcode_type (hệ ký hiệu, ví dụ QRCODE, EAN13, CODE128) và value (giá trị bị cắt cụt). Các getter có kiểu: getBarcodeType(), getValue().
• Khôi phục. Hành động của nhà phát triển: sửa dữ liệu mã vạch hoặc lựa chọn hệ ký hiệu.

BarcodeEncoderNotFoundException

• Khi nào nó được ném. Từ BarcodeEncoderRegistry khi kiểu encoder được yêu cầu không xác định hoặc cổng năng lực của nó đang đóng. Nó cũng hiện thực PSR-11 Psr\Container\NotFoundExceptionInterface, nên registry là một container tuân chuẩn. Thông báo nêu tên hệ ký hiệu và lý do.
• Context. Không ghi đè getContext(), nên nó trả về một mảng rỗng. type và reason có sẵn qua các getter getType() và getReason() cũng như trong thông báo.
• Khôi phục. Hành động của nhà phát triển: đăng ký encoder, hoặc cài đặt gói cung cấp nó (ví dụ nextpdf/pro cho Micro QR / DotCode / HanXin / JabCode).

Mật mã, mã hóa, và chữ ký

EncryptionException

• Khi nào nó được ném. Khi mã hóa hoặc giải mã PDF thất bại: lỗi mã hóa/giải mã AES-256-CBC, lỗi OpenSSL, kích thước IV không hợp lệ, lỗi tính toán hash, và lỗi tính giá trị UE/OE. Thường là một tiện ích mở rộng OpenSSL thiếu hoặc cấu hình sai, vật liệu khóa không hợp lệ, hoặc dữ liệu mã hóa bị hỏng. Thông báo nêu tên thao tác và thuật toán.
• Context. getContext() trả về algorithm (ví dụ AES-256-CBC) và operation (ví dụ encrypt, decrypt, key_derivation). Các getter có kiểu: getAlgorithm(), getOperation().
• Khôi phục. Hành động hạ tầng: đảm bảo OpenSSL có sẵn và được cấu hình đúng. Xem Mã hóa và quyền.

UnsupportedAlgorithmException

• Khi nào nó được ném. Khi một thuật toán mật mã không thể thực thi trong môi trường chạy hiện tại: thiếu một tiện ích mở rộng PHP bắt buộc, thư viện nền thiếu primitive, tiện ích hash đi kèm không thể tổng hợp một biến thể SHAKE/XOF, hoặc thuật toán không được đăng ký trong SignatureAlgorithmRegistry. Engine không được âm thầm suy giảm xuống một primitive yếu hơn, nên nó phơi bày điều này thay thế. Static factory nonFipsHostUnderFipsProfile() nêu ra nó (với định danh thuật toán regulatory-profile:fips) khi RegulatoryProfile::FIPS được chọn nhưng không thể xác nhận một provider OpenSSL đã được FIPS xác thực (cả FIPS_ABSENT và INDETERMINATE đều thất bại theo hướng đóng).
• Context. getContext() trả về algorithm (tên hoặc OID, ví dụ shake256, Ed25519, AES-256-GCM) và reason (người vận hành có thể hành động). Các getter có kiểu: getAlgorithm(), getReason().
• Khôi phục. Hành động của người vận hành: cài đặt tiện ích mở rộng còn thiếu hoặc nâng cấp môi trường chạy; với cổng FIPS, cài đặt một bản dựng OpenSSL đã được FIPS xác thực hoặc đặt NEXTPDF_FIPS_MODE một cách tường minh. Hành động của nhà phát triển: đăng ký một bộ mô tả thuật toán tùy biến qua SignatureAlgorithmRegistry::register().

SignatureException

• Khi nào nó được ném. Khi một thao tác chữ ký số thất bại: xử lý chứng thư và khóa riêng (phân tích PKCS#12, giải mã PEM/DER, xác thực X.509), dựng PKCS#7/CMS, định dạng chữ ký ECDSA, vi phạm kích thước container, mã hóa DER, và điều phối PAdES. Lỗi riêng cho TSA được báo cáo bởi TsaException chuyên biệt hơn thay thế. Hãy ưu tiên các factory có tên có kiểu hơn constructor theo vị trí; mỗi factory gắn nguyên nhân gốc vào phần đuôi thông báo. Ví dụ: ltvCapabilityMissing() (B-LT/B-LTA cần nextpdf/enterprise), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed(), họ Ed25519 (ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing(), và cặp trạng thái OCSP nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (RFC 6960 §4.2.1). Các factory này thất bại theo hướng đóng thay vì phát ra một chữ ký bị hạ cấp âm thầm.
• Context. getContext() trả về cert_info (subject DN hoặc thumbprint, hoặc rỗng), signature_level (cấp độ PAdES đã thử, ví dụ B-B, B-T, B-LT, B-LTA), và detail (chẩn đoán có thể hành động, rỗng với constructor theo vị trí cũ). Các getter có kiểu: getCertInfo(), getSignatureLevel(), getDetail().
• Khôi phục. Hành động của nhà phát triển: sửa cấu hình chứng thư/khóa. Với các factory thiếu năng lực, cài đặt gói được nêu tên. Xem Lỗi chữ ký và dấu thời gian để biết các mục triệu chứng-và-giải-pháp theo từng factory.

BlackPointCompensationUnsupportedException

• Khi nào nó được ném. Từ NullBlackPointCompensationTransform::transform() khi một caller yêu cầu adapter null áp dụng một phép biến đổi bù điểm đen ISO 18619 không phải Default. Adapter null là phương án dự phòng an toàn cho môi trường không có backend quản lý màu; tạo ra một mẫu đã biến đổi mà không có một module quản lý màu thực sẽ âm thầm báo cáo sai phép chuyển đổi. Khác với hầu hết các mục ở đây, lớp này mở rộng trực tiếp \RuntimeException, không phải NextPdfException, nên các đường catch (\RuntimeException) hiện có vẫn hoạt động.
• Context. Không có getContext(); nó là một \RuntimeException thuần. Chi tiết nằm trong thông báo.
• Khôi phục. Hành động của nhà phát triển: đăng ký một BlackPointCompensationTransform thực (LittleCMS, Argyll, thuần PHP), hoặc giới hạn /UseBlackPtComp về BlackPointCompensation::Default.

Lắp ráp tài liệu và khả năng truy cập

UnsupportedSourceDocumentException

• Khi nào nó được ném. Khi một tài liệu nguồn không thể được sao chép an toàn vào một output hợp nhất/tách và thao tác thất bại theo hướng đóng thay vì phát ra một kết quả hỏng hoặc bị tổn hại bảo mật. Hãy dùng các factory có tên: encrypted() (ISO 32000-2 §7.6 — không thể sao chép nội dung mà không có khóa), signed() (§12.8 — sao chép trang sẽ làm vô hiệu byte range của chữ ký), unsupportedStreamFilter() (một filter mà trình đọc object-graph không thể round-trip), multipleInteractiveForms() (một giới hạn đã ghi nhận: nhiều hơn một nguồn mang một /AcroForm không rỗng, §12.7), và splitWithInteractiveForm() (một giới hạn đã ghi nhận: tách trang một nguồn mang biểu mẫu sẽ làm mồ côi các widget). Mở rộng trực tiếp \RuntimeException, không phải NextPdfException.
• Context. Không có getContext(); nó là một \RuntimeException thuần. Nguyên nhân và số đối tượng bị ảnh hưởng được nêu tên trong thông báo.
• Khôi phục. Hành động của nhà phát triển: giải mã nguồn trước hoặc cung cấp khóa; với nguồn đã ký, hãy ký sau khi hợp nhất thay thế; với các hợp nhất nhiều biểu mẫu, làm phẳng hoặc gỡ các trường biểu mẫu của tất cả trừ một nguồn; với các lần tách trên nguồn mang biểu mẫu, làm phẳng biểu mẫu trước khi tách.

InvalidBcp47TagException

• Khi nào nó được ném. Từ Bcp47Validator::validate() khi một thẻ ngôn ngữ ứng viên bị hỏng khuôn theo ABNF RFC 5646 §2.1, hoặc thất bại ở bước tra cứu registry được tuyển chọn. Riêng cho lĩnh vực BCP-47 / ISO 14289-2:2024 §8.4.4, tách biệt khỏi InvalidConfigException nên các caller phía sau seam khả năng truy cập có thể bắt một kiểu hẹp. Cặp predicate Bcp47Validator::isWellFormed() / isValid() vẫn là bề mặt giá trị trả về tương thích ngược cho các caller ưu tiên rẽ nhánh hơn ngoại lệ.
• Context. getContext() trả về tag (ứng viên đúng như được cung cấp) và reason (một mã từ chối ổn định, máy đọc được, ví dụ empty-string, well-formed-shape, unregistered-primary, duplicate-variant). Các getter có kiểu: getTag(), getReason().
• Khôi phục. Hành động của nhà phát triển: sửa thẻ ngôn ngữ thành một thẻ BCP-47 hợp khuôn, đã đăng ký. Xem Phông chữ và gắn thẻ.

FormFieldAccessibilityException

• Khi nào nó được ném. Khi một trường biểu mẫu tương tác sẽ dựa vào một tên truy cập được tổng hợp (không do tác giả cung cấp) trong khi tạo ra một tài liệu PDF/UA với việc thực thi nghiêm ngặt tên-trường-truy-cập-được bật. Output PDF/UA mặc định phát ra một tên dự phòng tổng hợp vào /Contents của widget để một trường không bao giờ không có tên; chế độ nghiêm ngặt thay vào đó yêu cầu tác giả cung cấp một tên có ý nghĩa (một tooltip, hoặc một caption cho push button không có action) để người dùng trình đọc màn hình nhận được một mô tả thực (ISO 14289-2:2024 §8.10.2).
• Context. Không ghi đè getContext(), nên nó trả về một mảng rỗng. $fieldId là một thuộc tính công khai chỉ đọc; lý do nằm trong thông báo.
• Khôi phục. Hành động của nhà phát triển: cung cấp một tooltip / tên truy cập được cho trường được nêu tên trước khi tạo một tài liệu PDF/UA nghiêm ngặt, hoặc tắt chế độ nghiêm ngặt. Xem Xác thực PDF/A và PDF/UA.

VendorExtensionRegistryConflictException

• Khi nào nó được ném. Từ VendorExtensionRegistry::register() khi một caller đăng ký lại một tiền tố vendor của developer-extension PDF đã biết (ISO 32000-2:2020 §7.12.1) với một mô tả không khớp với siêu dữ liệu đã đăng ký. Các bộ mô tả là chỉ-thêm và được phát hiện xung đột; ngoại lệ có kiểu này đã thay thế một \RuntimeException chung nên các caller có thể bắt lớp cụ thể này.
• Context. getContext() trả về prefix, existing_description, và attempted_description. Các getter có kiểu: getPrefix(), getExistingDescription(), getAttemptedDescription().
• Khôi phục. Hành động của nhà phát triển: đăng ký tiền tố với mô tả hiện có, hoặc dùng một tiền tố khác; đừng ghi đè siêu dữ liệu đã đăng ký.

Xuất kiểm toán

AuditExportException

• Khi nào nó được ném. Khi lắp ráp bundle xuất kiểm toán, tạo ma trận truy vết, hoặc phép chiếu schema thất bại tại môi trường chạy. Bao quát I/O với claims.json / manifest.json, mã hóa/giải mã JSON của bundle chuẩn tắc, và lệch phiên bản schema trên đường tương thích ngược AuditExporter::projectToV1(). Thông báo nêu tên giai đoạn, artefact khi biết, và chi tiết.
• Context. getContext() trả về stage (ví dụ read_claims, encode_bundle, project_v1), detail, và artefact (đường dẫn hoặc schema_version đã kích hoạt lỗi). Các getter có kiểu: getStage(), getDetail(), getArtefact().
• Khôi phục. Hành động của bộ phận tuân thủ / DevOps: kiểm tra các đường dẫn artefact đầu vào, tạo lại claims.json từ một lần chạy sạch, hoặc dựng lại manifest trước khi thử xuất lại.

Các đối tượng giá trị vi phạm

Đây không phải là ngoại lệ. Chúng là các đối tượng giá trị bất biến mà engine trả về để mô tả một vi phạm riêng lẻ; chúng không mang getContext().

ComplianceViolation

• Nó là gì. Một đối tượng giá trị final readonly biểu diễn một lỗi quy tắc được báo cáo bởi một validator bên ngoài (veraPDF hoặc tương đương), bao gồm tham chiếu điều khoản ISO và vị trí trong cấu trúc PDF.
• Trường. Các thuộc tính công khai chỉ đọc: ruleId (định danh quy tắc của validator, ví dụ 6.1.2-1), clause (tham chiếu điều khoản ISO, ví dụ ISO 19005-1:2005, 6.1.2), severity (ví dụ error, warning), location (đường dẫn đối tượng trong cấu trúc PDF), và message (mô tả dễ đọc cho con người).
• Cách dùng. Kiểm tra tập hợp được một validator tuân thủ trả về; định tuyến hoặc hiển thị mỗi mục theo severity và clause. Xem Xác thực PDF/A và PDF/UA.

RuleViolation

• Nó là gì. Một đối tượng giá trị final readonly biểu diễn một vi phạm quy tắc nghiệp vụ Schematron / EN 16931, được trả về bởi SchematronRunnerInterface::runRules() và tổng hợp bên trong ValidationResult::$ruleViolations. Mức ổn định là experimental.
• Trường. Các thuộc tính công khai chỉ đọc: ruleId (định danh EN 16931 như BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n}, hoặc một pack riêng theo tier), severity (một enum RuleSeverity), message (văn bản quy tắc, en-GB), xpath (XPath vào XML nhúng, null cho các quy tắc phạm vi toàn tài liệu), và semanticPath (đường dẫn BG/BT theo dạng dấu-chấm như BG-22.BT-106, null cho các vi phạm cấu trúc).
• Cách dùng. Kiểm tra tập hợp trên kết quả xác thực; định tuyến hoặc hiển thị mỗi mục theo severity, ruleId, và locator.

Xem thêm

• Chỉ mục tài liệu tham khảo lỗi
• Chỉ mục cơ sở tri thức
• Lỗi chữ ký và dấu thời gian
• Mã hóa và quyền
• Phông chữ và gắn thẻ
• Xác thực PDF/A và PDF/UA