Branding — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu sâu cho module NextPDF\Enterprise\Branding. Module đánh dấu đầu ra đánh giá và để nguyên đầu ra trả phí. Một BrandingMode được phân giải từ giấy phép chọn một chiến lược; BrandingApplicator áp dụng chiến lược đã phân giải lên các byte PDF đã render. Dưới một giấy phép trả phí, phép biến đổi là phép đồng nhất: đầu ra không thay đổi từng byte, không cần thay đổi mã. Đối với quy trình đánh giá, hãy đọc trang năng lực Branding trước.

Tính khả dụng và cấp phép

Năng lực này được phát hành trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt bằng một envelope giấy phép hạng Enterprise. Một triển khai không có quyền đó sẽ không nạp các class của năng lực này. So sánh các phiên bản và lấy giấy phép.

Hệ thống con mang mã năng lực chuyên biệt enterprise.branding vì nó chi phối hành vi đánh giá trên tất cả các phiên bản. Chế độ branding được phân giải từ envelope giấy phép đã ký tại runtime; không có cờ ứng dụng nào chọn nó. Một giấy phép trả phí phân giải chế độ thành None và không bao giờ tạo ra đầu ra có branding. Không có bản build production nào để chuyển sang.

Bề mặt Public API

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
BrandingMode	—	None ('none'): không sửa đổi	—	—	Enum nền chuỗi; EvaluationWatermark ('evaluation') kích hoạt branding đánh giá.
BrandingStrategy	—	Hợp đồng được các điểm tích hợp tiêu thụ	—	—	Interface; caller không bao giờ rẽ nhánh trực tiếp trên BrandingMode.
BrandingStrategy::isActive	—	false với chiến lược null, true với chiến lược đánh giá	bool	—	false nghĩa là mọi phương thức khác trả về giá trị đồng nhất.
BrandingStrategy::buildPageWatermark	float $pageWidth, float $pageHeight (điểm)	Chuỗi rỗng khi không hoạt động; các toán tử hình mờ chéo khi hoạt động	string	—	Stream giả định có một tài nguyên phông /helvetica trên trang.
BrandingStrategy::decorateProducer	string $producer	Đồng nhất khi không hoạt động; thêm hậu tố đánh giá khi hoạt động	string	—	Hậu tố mặc định: [EVALUATION].
BrandingStrategy::decorateSubject	string $subject	Đồng nhất khi không hoạt động; thêm tiền tố đánh giá vào đầu khi hoạt động	string	—	Subject rỗng cho ra dấu hiệu đã cắt khoảng trắng.
BrandingStrategyFactory::create	BrandingMode $mode, ?EvaluationBrandingConfig $config = null	Ánh xạ None tới NullBrandingStrategy, EvaluationWatermark tới EvaluationBrandingStrategy	BrandingStrategy	—	Static; cấu hình null dùng giá trị mặc định.
EvaluationBrandingConfig::__construct	Sáu tham số đặt tên tùy chọn (text, suffix, prefix, size, gray, angle)	Mặc định: 48 pt, xám 0.85, 45 độ	Instance	InvalidArgumentException khi text rỗng, cỡ phông không dương, hoặc xám ngoài khoảng 0.0–1.0	final readonly; bất biến.
EvaluationBrandingStrategy	EvaluationBrandingConfig tùy chọn	Áp dụng hình mờ và trang trí metadata	—	—	final readonly; hiện thực BrandingStrategy.
NullBrandingStrategy	—	Đồng nhất trên mọi phương thức	—	—	Được chọn dưới một giấy phép trả phí.
BrandingApplicator::apply	string $pdfBytes, BrandingStrategy $strategy	Chiến lược không hoạt động: đầu vào được trả về từng byte; hoạt động: thêm một incremental update	string	BrandingApplicationException khi branding hoạt động không thể áp dụng an toàn	Phép biến đổi byte thuần túy, tất định.
BrandingApplicationException	—	Tín hiệu lỗi kết thúc, fail-closed	—	—	Mang SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE); factory unsupportedStructure().

Chữ ký điểm vào

enum BrandingMode: string
{
    case None = 'none';
    case EvaluationWatermark = 'evaluation';
}

public static function create(
    BrandingMode $mode,
    ?EvaluationBrandingConfig $config = null,
): BrandingStrategy

public function __construct(
    public string $watermarkText = 'EVALUATION COPY — Not for Production Use',
    public string $producerSuffix = ' [EVALUATION]',
    public string $subjectPrefix = '[EVALUATION] ',
    public float $watermarkFontSize = 48.0,
    public float $watermarkGray = 0.85,
    public float $watermarkAngle = 45.0,
)

public function apply(string $pdfBytes, BrandingStrategy $strategy): string

Hợp đồng hành vi

Phân giải chế độ và chiến lược. Trạng thái giấy phép — không phải mã ứng dụng — chọn BrandingMode. BrandingStrategyFactory::create ánh xạ None tới NullBrandingStrategy và EvaluationWatermark tới EvaluationBrandingStrategy. Các điểm tích hợp tiêu thụ interface BrandingStrategy và không bao giờ kiểm tra chế độ trực tiếp, nên logic branding vẫn được tập trung. Dưới một giấy phép trả phí, chiến lược null được chọn và đầu ra giống hệt đầu ra được tạo ra mà hoàn toàn không có hệ thống con branding.

Sinh hình mờ. buildPageWatermark phát ra các toán tử content-stream PDF cho một trang: một trạng thái đồ họa cô lập (q/Q), phông Helvetica standard-14 qua tên tài nguyên /helvetica, chế độ render text tô (fill), và một ma trận xoay đặt văn bản chéo qua tâm trang. Kiểu mặc định là văn bản 48 pt ở mức xám 0.85, xoay 45 độ. Việc căn giữa xấp xỉ chiều rộng văn bản theo số lượng glyph — cụm grapheme khi intl được nạp, các code point Unicode qua mbstring nếu không, và chiều dài byte là phương án dự phòng cuối cùng. Theo thiết kế, không tham chiếu độ rộng advance của từng glyph. Văn bản hình mờ được escape thành một chuỗi literal PDF theo ISO 32000-2:2020 §7.3.4.2 (dấu gạch chéo ngược và dấu ngoặc đơn).

Trang trí metadata. decorateProducer thêm hậu tố producer vào giá trị /Producer. decorateSubject thêm tiền tố subject vào đầu giá trị /Subject; một subject rỗng cho ra dấu hiệu đã cắt khoảng trắng, nên một tài liệu không có metadata subject vẫn được đánh dấu.

Áp dụng byte. BrandingApplicator::apply là bên tiêu thụ cuối cùng của điều khiển branding. Với một chiến lược không hoạt động, nó trả về đầu vào từng byte. Với một chiến lược hoạt động, nó thêm một incremental update duy nhất theo hình dạng được định nghĩa bởi ISO 32000-2:2020 §7.5.6: các byte gốc giữ nguyên, và phần thân được thêm chứa một đối tượng Info đã trang trí (tái sử dụng số đối tượng hiện có), một content stream hình mờ cùng một đối tượng trang đã cập nhật cho mỗi trang, và một cross-reference stream mới (/Type /XRef, /W [1 4 2]) có /Prev trỏ ngược về startxref trước đó. Phép biến đổi là thuần túy và tất định với một đầu vào và cấu hình cho trước.

Hợp đồng fail-closed. Khi chiến lược hoạt động, đầu vào phải có thể branding: một header %PDF-, không có mục /Encrypt, không có object stream (/ObjStm), một phần đuôi cross-reference-stream, và một tài nguyên phông /helvetica có thể phân giải từ mọi trang. Bất kỳ vi phạm nào cũng làm phát sinh BrandingApplicationException thay vì trả về các byte không có branding. Caller phải coi ngoại lệ là kết thúc và không được commit các byte gốc, chưa đánh dấu.

Trường hợp biên và chế độ lỗi

• Đầu ra có branding nghĩa là trạng thái giấy phép thuộc kiểu đánh giá. Điều đó phản ánh trạng thái giấy phép, không phải một lỗi.
• Hình mờ được căn giữa và chéo theo thiết kế. Nó không thể tinh chỉnh cho production; một giấy phép trả phí loại bỏ nó hoàn toàn.
• EvaluationBrandingConfig từ chối văn bản hình mờ rỗng, cỡ phông không dương, và mức xám ngoài khoảng 0.0–1.0 bằng InvalidArgumentException.
• Một chiến lược hoạt động mà không tạo ra thay đổi nào về Producer, Subject, hay hình mờ sẽ bị từ chối bằng BrandingApplicationException thay vì phát ra các byte trông như đã trả phí.
• Một trang không có /MediaBox khả dụng (vắng mặt hoặc kế thừa) được đóng hình mờ ở mặc định ISO 216 A4 là 595.276 × 841.890 điểm.
• /Contents ở cả dạng tham chiếu đơn và dạng mảng đều được hỗ trợ; tham chiếu hình mờ được thêm vào cuối cùng nên nó vẽ lên trên. Một trang không có /Contents sẽ được cấp một.
• Các giá trị chuỗi Info round-trip theo biểu diễn gốc của chúng: chuỗi thập lục phân (UTF-16BE) giữ nguyên thập lục phân, chuỗi literal giữ nguyên literal. Một khóa vắng mặt sẽ được thêm vào, mã hóa thập lục phân khi giá trị chứa ký tự không phải ASCII.
• Các tài liệu đã mã hóa bị từ chối: việc ghi lại các đối tượng chuỗi dưới /Encrypt sẽ cần khóa mã hóa tài liệu.
• Các lỗi mang mã ổn định SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE) để các pipeline tiêu thụ có thể dead-letter và audit đầu ra không thể branding.
• Module không thực hiện thao tác mật mã nào. Việc xác minh chữ ký envelope giấy phép thuộc về hệ thống con cấp phép; xem tài liệu tham chiếu sâu về Licensing.

Phù hợp tiêu chuẩn

Tuyên bố	Tiêu chuẩn	Điều khoản
Incremental update thêm các thay đổi vào cuối tệp và để nguyên nội dung gốc.	ISO 32000-2	§7.5.6
Phần cross-reference của bản cập nhật chỉ bao gồm các đối tượng đã thay đổi, và trailer được thêm mang một mục Prev định vị phần cross-reference trước đó.	ISO 32000-2	§7.5.6
Các chuỗi literal được viết trong dấu ngoặc đơn; dấu ngoặc đơn không cân bằng và dấu gạch chéo ngược cần được xử lý escape.	ISO 32000-2	§7.3.4.2

Tất cả các điều khoản được diễn giải lại; NextPDF không tái tạo văn bản quy phạm. NextPDF không đưa ra tuyên bố chứng nhận nào. Applicator ghi các incremental update theo hình dạng ISO 32000-2 đã trích dẫn như một tuyên bố năng lực; nó không phải là một writer được chứng nhận hay được kiểm định độc lập. Trang này chỉ mô tả hành vi runtime. Nó không đưa ra bảo hành nào, không nêu tuyên bố nào về tính đủ điều kiện hay hiệu lực pháp lý, và không cấu thành tư vấn pháp lý; các điều khoản của một đợt đánh giá hoặc thuê bao được định nghĩa duy nhất bởi thỏa thuận giấy phép.

Ghi chú phát triển

• BrandingMode, BrandingStrategy, cả hai chiến lược, và config mang @since 3.0.0; BrandingApplicator và BrandingApplicationException mang @since 3.1.0.
• Hệ thống con không thực hiện cuộc gọi mạng nào. Applicator chỉ đọc các trường cấu trúc mà nó ghi lại: các chuỗi trong dictionary Info, các dictionary trang, và phần đuôi cross-reference.
• Envelope giấy phép là một artifact đã ký mà runtime xác minh chữ ký của bên phát hành. Việc cấp phát, gia hạn và lưu trữ an toàn giấy phép là trách nhiệm của người vận hành.
• Tất cả các kiểu cụ thể đều là final; các chiến lược và config cũng là readonly. Hãy tạo một instance config mới để thay đổi kiểu hình mờ.
• BrandingStrategy::isActive() trả về false đảm bảo giá trị đồng nhất từ mọi phương thức khác; caller có thể short-circuit trên nó để tăng hiệu năng.
• Stream hình mờ tham chiếu tên tài nguyên /helvetica. Core đăng ký tài nguyên này cho branding của riêng nó; một tích hợp vô hiệu hóa branding của Core phải đảm bảo tài nguyên tồn tại.
• Applicator không tính digest nào; caller tính lại digest của các byte đã branding trước khi commit chúng.
• Chi tiết cơ chế nội bộ được giữ trong tài liệu nội bộ của repository nguồn và nằm ngoài phạm vi của sổ tay này.

Ranh giới công bố

Trang này chỉ tài liệu hóa hành vi có thể quan sát từ bên ngoài và bề mặt public API được hỗ trợ. Các đường dẫn namespace nội bộ, class trợ giúp, bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.

Xem thêm

• Branding — trang năng lực cho hệ thống con branding đánh giá.
• Dùng thử và branding đánh giá — câu chuyện đánh giá đầu-cuối.
• Licensing — tài liệu tham chiếu sâu
• Tổng quan Enterprise