Kho kiến thức khắc phục sự cố

Kho kiến thức này bao gồm những gì

Hãy dùng kho kiến thức này để đối chiếu lỗi bạn gặp với nguyên nhân và cách xử lý tương ứng. Mỗi mục đều xuất phát trực tiếp từ các lớp ngoại lệ, các bài kiểm thử đường lỗi và các chốt bảo vệ trong mã nguồn của engine, không dựa trên phỏng đoán. Nếu engine không có đường đi mã nào cho một lỗi nhất định, kho kiến thức này sẽ không tự dựng thêm một đường đi.

Kho kiến thức này gồm bốn trang chủ đề:

Xác thực chữ ký — chữ ký không hợp lệ, chuỗi chứng chỉ không đầy đủ, trạng thái thu hồi không xác định và lỗi dấu thời gian.
Xác thực PDF/A và PDF/UA — các vấn đề về Portable Document Format/Archive (PDF/A) và Portable Document Format/Universal Accessibility (PDF/UA), bao gồm thiếu output intent, nội dung chưa gắn thẻ, thiếu ngôn ngữ và lỗi phông chữ nhúng.
Phông chữ và gắn thẻ — không tìm thấy phông chữ, tạo tập con (subsetting), độ phủ CJK và các vấn đề về cây cấu trúc.
Mã hóa và quyền — lỗi giải mã và ranh giới của cờ quyền.

Cách đọc một mục

Mỗi mục có năm phần:

Triệu chứng — những gì bạn thấy: một lớp ngoại lệ, một đoạn thông báo, hoặc một kết luận từ trình xác thực phía sau.
Nguyên nhân có thể — điều kiện đầu vào hoặc cấu hình được engine báo cáo.
Bằng chứng / chẩn đoán — cách xác nhận nguyên nhân. Phần này nêu chính xác lớp ngoại lệ, trường getContext(), hoặc bài kiểm thử minh họa hành vi, để bạn có thể kiểm chứng thay vì suy đoán.
Cách xử lý — các bước theo thứ tự để loại bỏ nguyên nhân.
Liên quan — trang tham chiếu mô-đun hoặc mục liên quan nên đọc tiếp theo.

Xác định lỗi theo loại ngoại lệ

NextPDF nhận diện lỗi theo lớp PHP của lỗi đó, không theo mã lỗi dạng chuỗi. Không có hằng số NPDF-#### nào tồn tại trong các lớp ngoại lệ. Hãy bắt ngoại lệ lá khi bạn cần phản hồi cụ thể, và đọc ContextAwareExceptionInterface::getContext() để lấy các trường chẩn đoán có cấu trúc. Hãy dùng NextPDF\Exception\NextPdfException làm kiểu cơ sở; các lỗi bảo mật cũng dùng NextPDF\Security\Exception\SecurityException.

Để biết đầy đủ cây phân cấp và các quy tắc thứ tự bắt ngoại lệ, hãy đọc tài liệu tham chiếu ngoại lệ.

<?php

declare(strict_types=1);

use NextPDF\Exception\NextPdfException;
use NextPDF\Contracts\ContextAwareExceptionInterface;

try {
    // ... engine call ...
} catch (NextPdfException $e) {
    $context = $e instanceof ContextAwareExceptionInterface
        ? $e->getContext()
        : [];
    \error_log($e->getMessage());
    // $context carries snake_case primitive fields safe to serialize.
}

Phạm vi và ranh giới

Kho kiến thức này nói về cách engine phát hiện và báo cáo lỗi. Nó không bao quát các kết luận về độ tuân thủ từ những trình xác thực bên ngoài, chẳng hạn như veraPDF hoặc callas; các công cụ đó áp dụng bộ quy tắc riêng. Khi engine từ chối một thao tác để giữ tài liệu trong phạm vi một profile, chẳng hạn như từ chối mã hóa dưới PDF/A, mục liên quan sẽ nêu điều khoản chi phối và ngoại lệ thực thi điều khoản đó.

Xem thêm

Tài liệu tham chiếu ngoại lệ — cây phân cấp đầy đủ, thứ tự bắt ngoại lệ và hợp đồng getContext() (lấy ngữ cảnh)
Tài liệu tham chiếu độ tuân thủ — các trình kiểm tra profile PDF/A, PDF/UA và PDF/X

Thuật ngữ: ngoại lệ nhận biết ngữ cảnh