Config: cấu hình tài liệu bất biến

Tổng quan nhanh

Config là đối tượng cấu hình tài liệu bất biến. Khi bạn thay đổi một thiết lập, một wither có kiểu sẽ trả về một thể hiện mới; nhờ vậy, bạn có thể chia sẻ cấu hình an toàn giữa các tài liệu và worker. NextPdfConfig là lớp static riêng biệt, lưu các giới hạn an toàn của bộ phân tích Cascading Style Sheets (CSS) áp dụng trên toàn tiến trình.

Cài đặt

composer require nextpdf/core:^3

Cả hai lớp đều nằm trong gói core. Config đã có từ phiên bản 1.7.0. NextPdfConfig đã có từ phiên bản 2.2.0.

Tổng quan khái niệm

Config là lớp final readonly được đánh dấu bằng #[DisallowDynamicProperties]. Nó chỉ lưu các giá trị vô hướng và các value object final readonly, nên toàn bộ đồ thị đối tượng đều bất biến sâu. Nó không cung cấp setter with(string, mixed) tổng quát. Mỗi lần thay đổi đều dùng một wither có kiểu riêng. Có 19 wither như vậy: withPageSize(), withMargins(), withCompress(), cho đến withOutputColorProfile(), và mỗi wither dựng lại đối tượng bằng các đối số có tên. Việc dựng lại bằng đối số có tên là có chủ ý. Khi bạn thêm một tham số constructor, một wither hiện có sẽ không bao giờ âm thầm dịch chuyển một đối số theo vị trí. Một kiểm thử tương thích dùng reflection để cố định danh sách phương thức công khai và số lượng tham số. Chữ ký sai lệch sẽ khiến tích hợp liên tục (CI) thất bại.

Constructor cung cấp bề mặt cấu hình với các giá trị mặc định an toàn:

Tham số	Kiểu	Mặc định
pageSize	PageSize	PageSize(595.276, 841.890, 'A4')
margins	Margin	Margin(10.0, 10.0, 10.0, 10.0)
compress	bool	true
autoPageBreak	bool	true
breakMargin	float	20.0
lang	string (BCP-47)	''
fontsDirectory	string	''
imageCacheBytes	int	52_428_800
deterministic	?DeterministicSettings	null
cryptoPolicy	?CryptoPolicyInterface	null
branding	?BrandingConfig	null
degradationPolicy	DegradationPolicy	Balanced
degradationOverrides	array<string, DegradationPolicy>	[]
cssRenderingMode	CssRenderingMode	Normal
auditCollector	?AuditCollector	null
cssFeatureFlags	?CssFeatureFlags	null
cssLayoutMode	CssLayoutMode	Streaming
retainedNodeBudget	int	50_000
layoutTelemetryCollector	?LayoutTelemetryCollector	null
telemetryEnabled	bool	false
outputColorProfile	OutputColorProfile	DeviceRGB

Ba thiết lập áp đặt ràng buộc giá trị. retainedNodeBudget chấp nhận khoảng đóng [5_000, 100_000] (các hằng số RETAINED_NODE_BUDGET_MIN, RETAINED_NODE_BUDGET_MAX, mặc định RETAINED_NODE_BUDGET_DEFAULT). withRetainedNodeBudget() ném InvalidArgumentException khi nằm ngoài khoảng đó. effectiveRetainedNodeBudget() trả về 0 ở chế độ streaming. Nếu không, nó kẹp giá trị trở lại trong khoảng như một lớp kiểm tra phòng thủ chiều sâu, để chống lại việc dựng trực tiếp theo vị trí. validate() áp đặt các bất biến liên trường mà từng wither riêng lẻ không thể tự nhận biết. CssLayoutMode::Auto được dành riêng và ném NotImplementedException. CssRenderingMode::Safe kết hợp với CssLayoutMode::Retained sẽ ném IncompatibleRenderingModeException. auditCollector là bộ thu thập báo cáo kiểm toán do bên gọi cung cấp. Nó chỉ được dùng khi cssRenderingMode là CssRenderingMode::Audit, nơi nó điều khiển một khối Extensible Metadata Platform (XMP) nextpdfAudit riêng tư. Các chế độ kết xuất khác sẽ bỏ qua nó.

NextPdfConfig xử lý một mối quan tâm riêng. Nó là tiện ích static không thể khởi tạo, giữ các giới hạn của bộ phân tích CSS áp dụng trên toàn tiến trình. Các giới hạn là số byte tối đa của stylesheet (mặc định 512 KB) và độ sâu lồng nhau tối đa của CSS (mặc định 8). Đây là các ranh giới bảo mật chống cạn kiệt tài nguyên do đầu vào độc hại, không phải tùy chọn theo từng tài liệu. Vì vậy, chúng là static. Các setter kẹp giá trị về một ngưỡng sàn (max(1024, …) byte, độ sâu max(1, …)). resetDefaults() được đánh dấu @internal và chỉ dùng cho kiểm thử.

Bề mặt API

Ký hiệu	Loại	Thành viên chính
NextPDF\Core\Config	lớp final readonly	21 tham số constructor; 19 wither có kiểu; validate(), isSafeMode(), isRetainedMode(), effectiveRetainedNodeBudget(), resolveFeatureFlags()
NextPDF\Core\Config::RETAINED_NODE_BUDGET_MIN	const int	5_000
NextPDF\Core\Config::RETAINED_NODE_BUDGET_MAX	const int	100_000
NextPDF\Core\Config::RETAINED_NODE_BUDGET_DEFAULT	const int	50_000
NextPDF\Core\NextPdfConfig	lớp final	setMaxCssBytes(), getMaxCssBytes(), setMaxCssNestingDepth(), getMaxCssNestingDepth(), resetDefaults() (@internal)

Các wither: withPageSize, withMargins, withCompress, withAutoPageBreak, withLang, withFontsDirectory, withImageCacheBytes, withDeterministic, withCryptoPolicy, withBranding, withDegradationPolicy, withDegradationOverride, withCssRenderingMode, withCssFeatureFlags, withCssLayoutMode, withRetainedNodeBudget, withLayoutTelemetryCollector, withTelemetryEnabled, withOutputColorProfile.

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

Bắt đầu với các giá trị mặc định và điều chỉnh hai thiết lập.

<?php

declare(strict_types=1);

use NextPDF\Core\Config;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

$config = (new Config())
    ->withPageSize(PageSize::Letter())
    ->withMargins(Margin::uniform(18.0));

// Each wither returns a new instance; the original is unchanged.

Ví dụ mã — môi trường sản xuất

Tạo một cấu hình tất định đã được kiểm tra, đồng thời siết chặt các giới hạn CSS áp dụng trên toàn tiến trình đối với đầu vào không tin cậy.

<?php

declare(strict_types=1);

use NextPDF\Core\Config;
use NextPDF\Core\CssRenderingMode;
use NextPDF\Core\NextPdfConfig;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

$config = (new Config())
    ->withPageSize(PageSize::A4())
    ->withMargins(Margin::symmetric(vertical: 20.0, horizontal: 15.0))
    ->withCompress(true)
    ->withCssRenderingMode(CssRenderingMode::Safe);

// Reject mutually exclusive modes before generation starts.
$config->validate();

// Process-wide hardening for hostile stylesheet input.
NextPdfConfig::setMaxCssBytes(262_144);   // 256 KB
NextPdfConfig::setMaxCssNestingDepth(4);

Trường hợp biên và điểm cần lưu ý

• Config không áp đặt quy tắc liên trường nào cho đến khi bạn gọi validate(). Một wither không thể tự phát hiện xung đột Safe + Retained; hãy gọi validate() trước khi bắt đầu tạo.
• withRetainedNodeBudget() là wither duy nhất ném lỗi dựa trên đầu vào của chính nó (InvalidArgumentException khi nằm ngoài [5_000, 100_000]).
• effectiveRetainedNodeBudget() trả về 0 ở chế độ streaming. Giá trị đó báo hiệu “ngân sách Tier-1 không áp dụng”, chứ không phải “không cho phép node nào”.
• withLayoutTelemetryCollector() và withTelemetryEnabled() độc lập với nhau. Việc gắn một collector mà không bật telemetry sẽ chuẩn bị sẵn nó cho một đợt canary sau này. Bật telemetry mà không có collector là hợp lệ và không có tác dụng gì.
• NextPdfConfig áp dụng trên toàn tiến trình và là static. Một thay đổi ảnh hưởng đến mọi tài liệu trong tiến trình cho đến khi được đặt lại. Đây là một ranh giới bảo mật, không phải tùy chọn theo từng tài liệu. Đừng thay đổi nó trong luồng xử lý của từng yêu cầu.
• NextPdfConfig::resetDefaults() là @internal. Đừng gọi nó trong mã sản xuất.

Hiệu năng

Một wither cấp phát một Config mới và sao chép tham chiếu đến các value object hiện có. Thao tác này có độ phức tạp O(1) theo số lượng thiết lập và không thực hiện sao chép sâu, vì mọi giá trị được giữ lại đều bất biến. Các accessor của NextPdfConfig là thao tác đọc trường static, O(1). performance_budget mặc định cho trang tham chiếu này là wall_ms: 1500, peak_mb: 64.

Ghi chú bảo mật

NextPdfConfig giới hạn mức sử dụng tài nguyên của bộ phân tích. Giới hạn stylesheet mặc định 512 KB và giới hạn lồng nhau ở độ sâu 8 bảo vệ trước các cuộc tấn công từ chối dịch vụ do CSS quá lớn bất thường hoặc lồng nhau quá sâu. Hãy hạ thấp cả hai giới hạn khi nguồn stylesheet không tin cậy. Config::cryptoPolicy mang một CryptoPolicyInterface để thực thi chính sách mật mã, chẳng hạn như một hồ sơ Federal Information Processing Standards (FIPS). Theo mặc định, nó là null và được thiết lập qua withCryptoPolicy(). Config::deterministic kiểm soát các dấu thời gian và định danh cố định để đầu ra giống hệt theo từng byte và là bắt buộc cho các bản dựng tái lập được.

Tuân thủ

Mô-đun này là phần cấu hình của engine và không kèm theo trích dẫn tiêu chuẩn quy phạm nào. Các thiết lập điều khiển hành vi theo tiêu chuẩn, bao gồm outputColorProfile (phát OutputIntent), cryptoPolicy (FIPS), và deterministic (bản dựng tái lập được), được ghi chép theo các điều khoản tương ứng trong các mô-đun phát ra chúng.

Xem thêm

• /modules/core/document/ — thành phần sử dụng Config
• /modules/core/valueobjects/ — PageSize, Margin được sử dụng bởi Config
• /modules/core/contracts/ — CryptoPolicyInterface, DegradationPolicy
• /modules/core/event/ — Config được mang theo trong DocumentCreatedEvent
• /modules/core/exception/ — InvalidConfigException, NotImplementedException

Thuật ngữ: typed wither · degradation policy · value object