Support: tiện ích dùng chung + Clock + Sleeper

Tổng quan nhanh

Mô-đun Support chứa các tiện ích dùng chung mà engine sử dụng nội bộ. Mô-đun này cũng cung cấp một bề mặt công khai nhỏ: đồng hồ hệ thống PHP Standards Recommendation 20 (PSR-20), quy trình thu thập cảnh báo và các nguyên tố tuần tự hóa Portable Document Format (PDF). Phần lớn namespace này là hạ tầng nội bộ. Trang này ghi lại những phần bạn có thể tin cậy, đồng thời đánh dấu những phần chỉ dành cho sử dụng nội bộ.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Clock (PSR-20). SystemClock hiện thực Psr\Clock\ClockInterface. Phương thức now() của nó trả về thời gian hiện tại dưới dạng DateTimeImmutable. Mô hình PSR-20 định nghĩa một interface đồng hồ chỉ có một thao tác đọc, trả về thời gian hiện tại dưới dạng giá trị ngày-giờ bất biến (PSR-20 psr_20_clock#2.1). SystemClock là mặc định; engine dùng nó khi bạn không inject đồng hồ nào. Để có thời gian cố định trong kiểm thử, hãy inject một đồng hồ đóng băng cũng hiện thực interface đó. Hãy ghép đồng hồ với Config::deterministic khi bạn cần đầu ra giống hệt nhau đến từng byte.

Quy trình cảnh báo. WarningCollector là phương tiện chính trong bộ nhớ để chuyển tải các vấn đề kết xuất không nghiêm trọng. Engine thêm một Warning cho mỗi lần suy giảm có tính tất định, chẳng hạn như cột bảng bị ép hẹp, phông chữ không phân giải được hoặc thiếu glyph. Sau khi tạo, bạn đọc các cảnh báo qua Document::getWarnings(). Một Warning là một value object bất biến. Nó mang theo một WarningCode, một WarningSeverity (warning hoặc degraded), trang, loại phần tử, id tính năng, một cờ ngang bằng đã suy giảm, một thông điệp, một DegradationImpact và một id năng lực tùy chọn. WarningCode là một enum nền tảng chuỗi gồm các định danh ổn định. Các định danh dùng tiền tố NEXTPDF_W_, chẳng hạn NEXTPDF_W_FONT_UNRESOLVED, để bạn có thể so khớp chúng an toàn trong kiểm thử. addWithPolicy() áp dụng DegradationPolicy đang hoạt động. Với chính sách nghiêm ngặt, tác động về tuân thủ, ngữ nghĩa hoặc chặn sẽ ném DegradedException. Với chính sách cân bằng, chỉ tác động chặn mới ném ngoại lệ. Chính sách dễ dãi không bao giờ ném ngoại lệ.

Các nguyên tố PDF. PdfStringEscaper là nguồn chân lý duy nhất cho việc escape chuỗi và tên PDF. escapeLiteral() escape các ký tự bắt buộc trong một chuỗi literal PDF: reverse solidus, dấu ngoặc đơn, carriage return (CR), line feed (LF), horizontal tab (HT), backspace (BS) và form feed (FF). Nó cũng loại bỏ byte NUL. escapeName() mã hóa hex các byte nằm ngoài dải American Standard Code for Information Interchange (ASCII) có thể in được, cũng như các byte trong tập ký tự phân định PDF cho một name object. BinaryBuffer là bộ tích lũy nhị phân tối ưu cho ghi, dùng cho các object và luồng PDF. Ở chế độ streaming, nó tràn sang một handle php://temp đối với tài liệu lớn. Nó cũng hỗ trợ các thao tác trên dải byte mà việc nhúng chữ ký cần đến. PdfOperators lưu các chuỗi định dạng toán tử của luồng nội dung cho đường dẫn, văn bản, trạng thái đồ họa và phông chữ. Các lớp vẽ và phân tích cú pháp dùng chung những chuỗi đó.

BinaryBuffer, PdfOperators, và phần lớn phần còn lại của NextPDF\Support\ là hạ tầng nội bộ. Các lớp writer và vẽ sử dụng chúng. Trang này ghi lại chúng để tài liệu đầy đủ hơn và hỗ trợ kiểm toán. Chúng không phải là một phần của application programming interface (API) công khai được hỗ trợ. Thay vào đó, hãy phụ thuộc vào façade Document và namespace Contracts. SystemClock, WarningCollector, Warning, WarningCode, WarningSeverity, và DegradationImpact là các thành viên hướng ra công khai.

Bề mặt API

Ký hiệu	Loại	Khả kiến	Thành viên chính
NextPDF\Support\SystemClock	final class	public	now(): DateTimeImmutable (PSR-20 ClockInterface)
NextPDF\Support\WarningCollector	final class	public	add(), emit(), addWithPolicy(), getWarnings(), hasWarnings(), hasDegradedParity(), clear()
NextPDF\Support\Warning	final readonly class	public	$code, $severity, $page, $elementType, $featureId, $degradedParity, $message, $impact, $capabilityId
NextPDF\Support\WarningCode	string enum	public	các định danh NEXTPDF_W_* ổn định
NextPDF\Support\WarningSeverity	string enum	public	Warning, Degraded
NextPDF\Support\DegradationImpact	string enum	public	Cosmetic, LayoutRisk, SemanticLoss, ComplianceRisk, Blocking
NextPDF\Support\PdfStringEscaper	final readonly class	internal	escapeLiteral(), escapeName() (static)
NextPDF\Support\BinaryBuffer	final class	internal	write(), writeStream(), replaceAt(), extract(), enableStreaming(), getContents()
NextPDF\Support\PdfOperators	final class	internal	các hằng chuỗi định dạng toán tử của luồng nội dung

Ví dụ mã — Bắt đầu nhanh

Đọc các cảnh báo đã thu thập sau khi tạo xong.

<?php

declare(strict_types=1);

use NextPDF\Support\WarningCollector;

$collector = new WarningCollector();

// The engine appends warnings during rendering. After generation:
if ($collector->hasWarnings()) {
    foreach ($collector->getWarnings() as $warning) {
        \printf(
            "[%s] page %d: %s\n",
            $warning->code->value,
            $warning->page,
            $warning->message,
        );
    }
}

Ví dụ mã — Sản xuất

Inject một đồng hồ để thời gian trở nên tất định, và coi cảnh báo ngang bằng đã suy giảm như lỗi build.

<?php

declare(strict_types=1);

use NextPDF\Support\SystemClock;
use NextPDF\Support\WarningCollector;
use Psr\Clock\ClockInterface;

// Production uses the real system clock.
$clock = new SystemClock();
$now = $clock->now();          // DateTimeImmutable
$epoch = $now->getTimestamp(); // int

// In tests, swap in any ClockInterface that returns a fixed instant
// (the parameter is typed to the PSR-20 interface, not SystemClock).
function buildReport(ClockInterface $clock): \DateTimeImmutable
{
    return $clock->now();
}

$collector = new WarningCollector();
// ... run generation ...
if ($collector->hasDegradedParity()) {
    throw new \RuntimeException('Output parity degraded; failing the build.');
}

Trường hợp biên & điều cần lưu ý

• SystemClock::now() trả về một DateTimeImmutable mới ở mỗi lần gọi. Đừng giả định hai lần gọi sẽ trả về cùng một thời điểm. Để có thời gian cố định, hãy inject một đồng hồ đóng băng.
• WarningCollector nằm trong bộ nhớ và gắn với từng thực thể. Nó là kênh cảnh báo chính. Đầu ra sidecar JavaScript Object Notation (JSON) và đầu ra lỗi chuẩn (STDERR) của giao diện dòng lệnh (CLI) được phát ở ranh giới đầu ra, chứ không phải bởi chính collector.
• addWithPolicy() có thể ném DegradedException giữa quá trình kết xuất dưới chính sách nghiêm ngặt. Hãy bắt nó ở ranh giới tạo nếu bạn cần đầu ra một phần.
• WarningCode có giá trị là các chuỗi ổn định. Hãy so khớp theo case của enum, không so theo nội dung thông điệp, vốn dành cho người đọc và có thể thay đổi.
• BinaryBuffer::getLength() là một bí danh có chủ ý của getOffset() để ngang bằng với interface luồng. Cả hai đều trả về cùng một bộ đếm byte.
• Hãy coi PdfStringEscaper, BinaryBuffer, và PdfOperators là hạ tầng nội bộ. Chúng không nằm trong cam kết ổn định của API công khai.

Hiệu năng

SystemClock::now() tạo một object và chạy ở O(1). Các thao tác thêm của WarningCollector là thao tác đẩy vào danh sách với O(1) trung bình. getWarnings() trả về danh sách nền tảng. Ở chế độ streaming, BinaryBuffer giữ dữ liệu trong bộ nhớ tới ngưỡng maxmemory (mặc định 2 MB) trước khi tràn ra đĩa, giúp đỉnh bộ nhớ ổn định với tài liệu lớn. performance_budget mặc định cho trang tham khảo này là wall_ms: 1500, peak_mb: 64.

Lưu ý bảo mật

Hãy dùng bề mặt đồng hồ để loại bỏ tính bất định của wall-clock khỏi đầu ra đã ký và đóng dấu thời gian, bằng cách inject một đồng hồ cố định cùng với Config::deterministic. PdfStringEscaper là escaper duy nhất có thể kiểm toán cho đầu ra chuỗi và tên PDF. Hãy định tuyến mọi thao tác phát chuỗi qua nó để ngăn tiêm nội dung thông qua dấu ngoặc đơn hoặc ký tự phân định chưa được escape trong văn bản do người dùng cung cấp. Cảnh báo có thể mang theo các chi tiết bắt nguồn từ tài liệu, chẳng hạn như loại phần tử và id tính năng. Hãy làm sạch đầu ra cảnh báo trước khi chuyển tiếp tới log sink ít tin cậy.

Tuân thủ

Tiêu chuẩn	Điều khoản	Chủ đề
PSR-20 (PHP-FIG)	psr_20_clock#2.1	Thao tác đọc đồng hồ trả về một ngày-giờ bất biến
ISO 32000-2:2020	§7.3.4.2 / §7.3.5	Escape chuỗi literal và name object (diễn giải lại; không trích nguyên văn ISO, không ghim chunk)

SystemClock hiện thực PSR-20 ClockInterface. Escaper tuân theo các quy tắc ký tự của chuỗi literal PDF và name object. Văn bản ISO được diễn giải lại theo chính sách trích dẫn của trang web; không ghim chunk nguyên văn nào.

Xem thêm

• /modules/core/exception/ — DegradedException được ném bởi addWithPolicy()
• /modules/core/contracts/ — DegradationPolicy, Capability
• /modules/core/observability/ — chuyển tiếp cảnh báo và số liệu đo
• /modules/core/config/ — Config::deterministic ghép với đồng hồ
• /modules/core/writer/ — bên tiêu thụ nội bộ của BinaryBuffer và PdfOperators

Bảng thuật ngữ: PSR-20 · chính sách suy giảm · value object