Exception: hệ phân cấp ngoại lệ được định kiểu

Tổng quan nhanh

Mọi ngoại lệ do NextPDF ném ra đều kế thừa từ một lớp cơ sở trừu tượng duy nhất, NextPdfException, vì vậy bạn có thể xử lý mọi lỗi của engine chỉ bằng một lệnh catch. Mỗi ngoại lệ theo lĩnh vực đều triển khai ContextAwareExceptionInterface và cung cấp các trường chẩn đoán có cấu trúc để ghi log và giám sát hiệu năng ứng dụng (APM), không cần phân tích chuỗi thông báo.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Hệ thống phân cấp có ba lớp:

RuntimeException (PHP SPL)
  └── NextPdfException (abstract; implements ContextAwareExceptionInterface)
        ├── InvalidConfigException
        ├── FontNotFoundException
        ├── FontParsingException
        ├── ImageProcessingException
        ├── SignatureException
        ├── EncryptionException
        ├── WriterException
        ├── PageLayoutException
        ├── HtmlParsingException
        ├── CompressionException
        ├── NotImplementedException
        ├── … (23 domain exceptions total)
        └── Strict\StrictModeViolation (abstract)
              ├── Strict\IncompatibleRenderingModeException
              ├── Strict\OracleConformanceFailure
              └── Strict\UnregisteredCssDeviation

NextPdfException kế thừa từ RuntimeException trong Standard PHP Library (SPL). Bắt RuntimeException cũng bắt được các lỗi của NextPDF. Bắt NextPdfException sẽ thu hẹp trình xử lý xuống chỉ còn lỗi của engine. Hãy bắt một lớp lá để khắc phục đúng trọng tâm. Nhánh con Strict\ gom các vi phạm chế độ tuân thủ dưới lớp trừu tượng StrictModeViolation, và lớp này cũng kế thừa từ NextPdfException.

Ngữ cảnh, không phải mã dạng chuỗi. NextPDF nhận diện một lỗi bằng kiểu PHP của lỗi đó, chứ không bằng mã lỗi dạng chuỗi. Các lớp ngoại lệ không định nghĩa hằng số mã NPDF-#### nào. Thay vào đó, ContextAwareExceptionInterface::getContext() trả về một array<string, mixed> gồm các trường nguyên thủy theo snake_case, an toàn khi tuần tự hóa vào log hoặc payload APM. NextPdfException::getContext() trả về [] theo mặc định. Mỗi ngoại lệ theo lĩnh vực ghi đè phương thức này bằng các trường dành riêng cho lỗi đó. Ví dụ, FontNotFoundException::getContext() trả về font_name, search_paths, và fallback_attempted. WriterException trả về output_path và writer_state. InvalidConfigException trả về config_key, given_value, và expected_type. Các định danh chuỗi ổn định NEXTPDF_W_* thuộc về enum WarningCode dành cho cảnh báo không nghiêm trọng trong module Support, chứ không thuộc về các ngoại lệ.

Khả năng hành động. Docblock của mỗi lớp ngoại lệ theo lĩnh vực nêu rõ ai có thể xử lý nó: nhà phát triển, hạ tầng, hay bên gọi thư viện. InvalidConfigException là lỗi của nhà phát triển; hãy sửa cấu hình. FontNotFoundException là lỗi của nhà phát triển hoặc hạ tầng; hãy kiểm tra đường dẫn hoặc quyền truy cập tệp. WriterException là lỗi hạ tầng; hãy kiểm tra ổ đĩa, quyền truy cập, hoặc luồng đầu ra. NotImplementedException là lỗi của bên gọi; hãy gỡ bỏ lệnh gọi hoặc ghim vào một bản phát hành có triển khai phần tiếp theo được nêu tên. Một số ngoại lệ cung cấp các hàm dựng được đặt tên cho từng nguyên nhân gốc rễ cụ thể: SignatureException::ltvCapabilityMissing(), ::tsaRequired(), và tương tự. Người vận hành nhìn thấy nguyên nhân thực sự thay vì một thông báo chung chung.

Bề mặt API

Ký hiệu	Loại	Thành viên chính
`NextPDF\Contracts\ContextAwareExceptionInterface`	interface	`getContext(): array<string, mixed>`
`NextPDF\Exception\NextPdfException`	lớp trừu tượng	kế thừa `RuntimeException`; `getContext()` (mặc định `[]`)
`NextPDF\Exception\InvalidConfigException`	final	`getConfigKey()`, `getGivenValue()`, `getExpectedType()`, `getContext()`
`NextPDF\Exception\FontNotFoundException`	final	`getFontName()`, `getSearchPaths()`, `wasFallbackAttempted()`, `getContext()`
`NextPDF\Exception\SignatureException`	final	`getCertInfo()`, `getSignatureLevel()`, `getDetail()`, `getContext()`; hàm dựng được đặt tên `ltvCapabilityMissing()`, `tsaRequired()`, `httpClientMissing()`, …
`NextPDF\Exception\WriterException`	final	`getOutputPath()`, `getWriterState()`, `getContext()`
`NextPDF\Exception\PageLayoutException`	final	`getPageNumber()`, `getContext()`
`NextPDF\Exception\NotImplementedException`	final	`$feature`, `$followUp`
`NextPDF\Exception\Strict\StrictModeViolation`	trừu tượng	kế thừa `NextPdfException`
`NextPDF\Exception\Strict\IncompatibleRenderingModeException`	final	kế thừa `StrictModeViolation`

Danh sách đầy đủ các lớp lá (23): BarcodeEncoderNotFoundException, BarcodeException, CompressionException, ContentStreamBalanceException, CssParserLimitExceededException, CssResolutionBudgetExceededException, EncryptionException, FontNotFoundException, FontParsingException, GraphicsStateBalanceException, HtmlParsingException, ImageProcessingException, InvalidConfigException, LinearizationInvariantException, LinearizationUnimplementedException, MissingShadingResourceException, NotImplementedException, PageLayoutException, PdfRViolationException, SignatureException, TemplateException, UnsupportedAlgorithmException, WriterException.

Mẫu mã — Bắt đầu nhanh

Bắt mọi lỗi của engine bằng cách bắt kiểu cơ sở.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Exception\NextPdfException;

try {
    $doc = Document::createStandalone();
    $doc->addPage();
    $doc->setFont('helvetica', '', 12);
    $doc->cell(0, 10, 'Hello');
    $doc->save('out.pdf');
} catch (NextPdfException $e) {
    \error_log($e->getMessage());
}

Ví dụ chạy được examples/15-exception-handling.php minh họa mẫu này.

Mẫu mã — Sản xuất

Khắc phục ở cấp lớp lá và gửi ngữ cảnh có cấu trúc đến luồng xử lý log.

<?php

declare(strict_types=1);

use NextPDF\Contracts\ContextAwareExceptionInterface;
use NextPDF\Core\Document;
use NextPDF\Exception\FontNotFoundException;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

function render(Document $doc, LoggerInterface $logger): void
{
    try {
        $doc->setFont('Brand-Sans', '', 12);
        $doc->cell(0, 10, 'Invoice');
        $doc->save('invoice.pdf');
    } catch (FontNotFoundException $e) {
        // Targeted recovery: fall back to a built-in font.
        $logger->warning($e->getMessage(), $e->getContext());
        $doc->setFont('helvetica', '', 12);
        $doc->save('invoice.pdf');
    } catch (NextPdfException $e) {
        // Any other engine error: structured context, then rethrow.
        $context = $e instanceof ContextAwareExceptionInterface
            ? $e->getContext()
            : [];
        $logger->error($e->getMessage(), $context);
        throw $e;
    }
}

Trường hợp đặc biệt & điểm cần lưu ý

Thứ tự bắt rất quan trọng. Hãy liệt kê các lớp lá trước NextPdfException; một catch (NextPdfException) đặt ở đầu sẽ bắt hết mọi lớp con.
getContext() dùng khóa snake_case, và giá trị là kiểu nguyên thủy hoặc danh sách kiểu nguyên thủy, không có đối tượng lồng nhau. Payload an toàn khi tuần tự hóa thành JavaScript Object Notation (JSON).
Lớp cơ sở NextPdfException::getContext() trả về []. Một lớp con không ghi đè phương thức này sẽ không mang theo trường có cấu trúc nào. Trong trường hợp đó, hãy dựa vào getMessage().
NextPdfException là trừu tượng; bạn không thể khởi tạo trực tiếp lớp này. Hãy ném ra một lớp lá cụ thể.
NotImplementedException cố ý gây chú ý. Nó báo hiệu một phần triển khai bị cố ý để trống, không phải một lỗi nhất thời. Đừng thử lại nó.
Strict\* cho thấy một vi phạm hợp đồng ở chế độ tuân thủ, không phải một lỗi thời gian chạy có thể khắc phục. Hãy xem chúng như khiếm khuyết về cấu hình hoặc đầu vào.
Không có hằng số mã lỗi dạng chuỗi nào. Hãy so khớp theo kiểu của ngoại lệ. Hãy chuyển tiếp getContext() cho các bên tiêu thụ bằng máy.

Hiệu năng

Việc dựng một ngoại lệ thực hiện một lần cấp phát đối tượng cùng với lệnh gọi sprintf để dựng thông báo: O(1). getContext() trả về một mảng kết hợp nhỏ được dựng từ các trường đã có sẵn: O(1) theo số lượng trường. Các ngoại lệ chạy trên đường lỗi, không phải đường nóng. Chi phí này không đáng kể so với phần việc đã thất bại. performance_budget mặc định cho trang tham chiếu này là wall_ms: 1500, peak_mb: 64.

Lưu ý bảo mật

Các trường ngữ cảnh có thể mang theo chi tiết bắt nguồn từ tài liệu. FontNotFoundException bao gồm các đường dẫn tìm kiếm trên hệ thống tệp, WriterException bao gồm đường dẫn đầu ra, và InvalidConfigException bao gồm giá trị được cung cấp. Trước khi chuyển tiếp ngữ cảnh đến một log sink có độ tin cậy thấp, hãy làm sạch các trường hoặc chỉ truyền một danh sách cho phép gồm các khóa, vì đường dẫn và giá trị có thể làm lộ bố cục triển khai hoặc đầu vào của người dùng. Thông báo ngoại lệ dành cho con người đọc và có thể bao gồm cùng những chi tiết đó. Đừng hiển thị thông báo thô cho người dùng cuối trong ngữ cảnh nhạy cảm về bảo mật. SignatureException cố ý đưa nguyên nhân gốc rễ cụ thể, chẳng hạn như một gói bị thiếu hoặc một Uniform Resource Locator (URL) rỗng cho một Time Stamping Authority (TSA), vào thông báo để người vận hành có thể phân loại sự cố mà không cần dò tìm các điểm gọi. Chi tiết đó dành cho người vận hành, không dành cho người dùng cuối.

Tuân thủ

Module này định nghĩa một mô hình lỗi của engine và không mang theo trích dẫn tiêu chuẩn quy phạm nào. Các ngoại lệ được ném ra do vi phạm tiêu chuẩn, ví dụ PdfRViolationException hoặc Strict\OracleConformanceFailure, tham chiếu điều khoản chi phối của chúng trong module phát hiện vi phạm, chứ không phải ở đây.

Xem thêm

/modules/core/contracts/ — ContextAwareExceptionInterface (định nghĩa)
/modules/core/observability/ — chuyển tiếp getContext() đến APM
/modules/core/config/ — InvalidConfigException, NotImplementedException
/modules/core/support/ — DegradedException; WarningCode (NEXTPDF_W_*)
/modules/core/event/ — InvalidConfigException từ addListener()

Bảng thuật ngữ: ngoại lệ nhận biết ngữ cảnh · chính sách suy giảm