Branding — เอกสารอ้างอิงเชิงลึก

ภาพรวมโดยย่อ

หน้านี้เป็นเอกสารอ้างอิงเชิงลึกสำหรับโมดูล NextPDF\Enterprise\Branding โมดูลนี้ทำเครื่องหมายผลลัพธ์โหมดประเมินและปล่อยผลลัพธ์แบบชำระเงินไว้โดยไม่แตะต้อง BrandingMode ที่ resolve จากสิทธิ์การใช้งานจะเลือกกลยุทธ์ และ BrandingApplicator จะใช้กลยุทธ์ที่ resolve แล้วกับไบต์ PDF ที่เรนเดอร์ ภายใต้สิทธิ์การใช้งานแบบชำระเงินการแปลงจะเป็น identity คือผลลัพธ์ไม่เปลี่ยนแปลงแบบไบต์ต่อไบต์โดยไม่ต้องเปลี่ยนแปลงโค้ด สำหรับเวิร์กโฟลว์โหมดประเมิน โปรดอ่านหน้าความสามารถ Brandingก่อน

ความพร้อมใช้งานและสิทธิ์การใช้งาน

ความสามารถนี้จัดส่งใน NextPDF Enterprise (nextpdf/enterprise) และเปิดใช้งานด้วยซองสิทธิ์การใช้งานระดับ Enterprise การดีพลอยที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและรับสิทธิ์การใช้งาน

ระบบย่อยนี้พกโค้ดความสามารถเฉพาะ enterprise.branding เพราะมันควบคุมพฤติกรรมโหมดประเมินข้ามทุกรุ่น โหมดการแสดงแบรนด์ถูก resolve จากซองสิทธิ์การใช้งานที่ลงนามในขณะรันไทม์ ไม่มีแฟล็กของแอปพลิเคชันที่เลือกมัน สิทธิ์การใช้งานแบบชำระเงินจะ resolve โหมดเป็น None และไม่เคยสร้างผลลัพธ์ที่มีแบรนด์ ไม่มีบิลด์การใช้งานจริงให้สลับ

พื้นผิว API สาธารณะ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
BrandingMode	—	None ('none'): ไม่มีการแก้ไข	—	—	enum ที่หนุนด้วย string; EvaluationWatermark ('evaluation') เปิดใช้งานการแสดงแบรนด์โหมดประเมิน
BrandingStrategy	—	สัญญาที่จุดผสานรวมเรียกใช้	—	—	อินเทอร์เฟซ ผู้เรียกไม่แยกเงื่อนไขบน BrandingMode โดยตรง
BrandingStrategy::isActive	—	false สำหรับกลยุทธ์ null, true สำหรับกลยุทธ์โหมดประเมิน	bool	—	false หมายความว่าเมธอดอื่นทุกตัวคืนค่า identity
BrandingStrategy::buildPageWatermark	float $pageWidth, float $pageHeight (จุด)	สตริงว่างเมื่อไม่ทำงาน; ตัวดำเนินการลายน้ำแนวทแยงเมื่อทำงาน	string	—	สตรีมสมมติว่ามีทรัพยากรฟอนต์ /helvetica บนหน้า
BrandingStrategy::decorateProducer	string $producer	identity เมื่อไม่ทำงาน; ต่อท้ายคำต่อท้ายโหมดประเมินเมื่อทำงาน	string	—	คำต่อท้ายเริ่มต้น: [EVALUATION]
BrandingStrategy::decorateSubject	string $subject	identity เมื่อไม่ทำงาน; นำหน้าคำนำหน้าโหมดประเมินเมื่อทำงาน	string	—	subject ว่างจะให้เครื่องหมายที่ตัดช่องว่างแล้ว
BrandingStrategyFactory::create	BrandingMode $mode, ?EvaluationBrandingConfig $config = null	แมป None เป็น NullBrandingStrategy, EvaluationWatermark เป็น EvaluationBrandingStrategy	BrandingStrategy	—	static; config เป็น null ใช้ค่าเริ่มต้น
EvaluationBrandingConfig::__construct	พารามิเตอร์แบบมีชื่อที่ไม่บังคับหกตัว (text, suffix, prefix, size, gray, angle)	ค่าเริ่มต้น: 48 pt, gray 0.85, 45 องศา	อินสแตนซ์	InvalidArgumentException เมื่อ text ว่าง ขนาดฟอนต์ไม่เป็นบวก หรือ gray อยู่นอกช่วง 0.0–1.0	final readonly; ไม่เปลี่ยนแปลงได้
EvaluationBrandingStrategy	EvaluationBrandingConfig ที่ไม่บังคับ	ใช้ลายน้ำและการตกแต่งข้อมูลเมตา	—	—	final readonly; implement BrandingStrategy
NullBrandingStrategy	—	identity ในทุกเมธอด	—	—	ถูกเลือกภายใต้สิทธิ์การใช้งานแบบชำระเงิน
BrandingApplicator::apply	string $pdfBytes, BrandingStrategy $strategy	กลยุทธ์ที่ไม่ทำงาน: คืนอินพุตแบบไบต์ต่อไบต์; ที่ทำงาน: ต่อท้าย incremental update หนึ่งครั้ง	string	BrandingApplicationException เมื่อไม่สามารถใช้การแสดงแบรนด์ที่ทำงานได้อย่างปลอดภัย	การแปลงไบต์แบบบริสุทธิ์และกำหนดได้แน่นอน
BrandingApplicationException	—	สัญญาณความล้มเหลวขั้นสุดท้ายแบบ fail-closed	—	—	พก SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE); factory unsupportedStructure()

ลายเซ็นจุดเริ่มต้น

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

สัญญาด้านพฤติกรรม

การ resolve โหมดและกลยุทธ์ สถานะสิทธิ์การใช้งาน — ไม่ใช่โค้ดของแอปพลิเคชัน — เป็นตัวเลือก BrandingMode BrandingStrategyFactory::create แมป None เป็น NullBrandingStrategy และ EvaluationWatermark เป็น EvaluationBrandingStrategy จุดผสานรวมเรียกใช้อินเทอร์เฟซ BrandingStrategy และไม่ตรวจสอบโหมดโดยตรง ตรรกะการแสดงแบรนด์จึงรวมศูนย์อยู่ที่เดียว ภายใต้สิทธิ์การใช้งานแบบชำระเงินกลยุทธ์ null ถูกเลือกและผลลัพธ์เหมือนกับผลลัพธ์ที่สร้างขึ้นโดยไม่มีระบบย่อยการแสดงแบรนด์เลย

การสร้างลายน้ำ buildPageWatermark ปล่อยตัวดำเนินการ content-stream ของ PDF สำหรับหนึ่งหน้า ได้แก่ graphics state ที่แยกออกมา (q/Q) ฟอนต์ Helvetica แบบ standard-14 ผ่านชื่อทรัพยากร /helvetica โหมดการเรนเดอร์ข้อความแบบ fill และเมทริกซ์การหมุนที่วางข้อความในแนวทแยงผ่านจุดกึ่งกลางหน้า สไตล์เริ่มต้นคือข้อความ 48 pt ที่ระดับสีเทา 0.85 หมุน 45 องศา การจัดกึ่งกลางประมาณความกว้างข้อความจากจำนวน glyph — grapheme cluster เมื่อโหลด intl, จุดโค้ด Unicode ผ่าน mbstring ในกรณีอื่น และความยาวไบต์เป็นทางเลือกสุดท้าย ไม่มีการอ้างอิงความกว้าง advance ต่อ glyph ตามการออกแบบ ข้อความลายน้ำถูก escape เป็น literal string ของ PDF ตาม ISO 32000-2:2020 §7.3.4.2 (backslash และวงเล็บ)

การตกแต่งข้อมูลเมตา decorateProducer ต่อท้ายคำต่อท้าย producer ลงในค่า /Producer decorateSubject นำหน้าคำนำหน้า subject ลงในค่า /Subject subject ที่ว่างจะให้เครื่องหมายที่ตัดช่องว่างแล้ว ดังนั้นเอกสารที่ไม่มีข้อมูลเมตา subject ก็ยังถูกทำเครื่องหมาย

การใช้งานระดับไบต์ BrandingApplicator::apply เป็นผู้บริโภคขั้นสุดท้ายของการควบคุมการแสดงแบรนด์ เมื่อกลยุทธ์ไม่ทำงานมันจะคืนอินพุตแบบไบต์ต่อไบต์ เมื่อกลยุทธ์ทำงานมันจะต่อท้าย incremental update เดียวในรูปแบบที่กำหนดโดย ISO 32000-2:2020 §7.5.6 คือ ไบต์เดิมยังคงอยู่ครบถ้วน และเนื้อหาที่ต่อท้ายมี Info object ที่ตกแต่งแล้ว (ใช้หมายเลข object เดิมซ้ำ) content stream ลายน้ำหนึ่งรายการพร้อม page object ที่อัปเดตหนึ่งรายการต่อหน้า และ cross-reference stream ใหม่ (/Type /XRef, /W [1 4 2]) ที่ /Prev ชี้กลับไปยัง startxref ก่อนหน้า การแปลงเป็นแบบบริสุทธิ์และกำหนดได้แน่นอนสำหรับอินพุตและการกำหนดค่าที่ให้มา

สัญญาแบบ fail-closed เมื่อกลยุทธ์ทำงาน อินพุตต้องสามารถแสดงแบรนด์ได้ ได้แก่ ส่วนหัว %PDF- ไม่มีรายการ /Encrypt ไม่มี object stream (/ObjStm) มีส่วนท้ายแบบ cross-reference-stream และมีทรัพยากรฟอนต์ /helvetica ที่ resolve ได้จากทุกหน้า การละเมิดใด ๆ จะโยน BrandingApplicationException แทนการคืนไบต์ที่ไม่มีแบรนด์ ผู้เรียกต้องถือว่า exception เป็นขั้นสุดท้ายและต้องไม่คอมมิตไบต์เดิมที่ไม่ได้ทำเครื่องหมาย

กรณีขอบและโหมดความล้มเหลว

• ผลลัพธ์ที่มีแบรนด์หมายความว่าสถานะสิทธิ์การใช้งานเป็นแบบโหมดประเมิน ซึ่งสะท้อนสถานะสิทธิ์การใช้งาน ไม่ใช่ข้อบกพร่อง
• ลายน้ำอยู่กึ่งกลางและแนวทแยงตามการออกแบบ มันปรับแต่งสำหรับการใช้งานจริงไม่ได้ สิทธิ์การใช้งานแบบชำระเงินจะลบมันออกทั้งหมด
• EvaluationBrandingConfig ปฏิเสธข้อความลายน้ำที่ว่าง ขนาดฟอนต์ที่ไม่เป็นบวก และระดับสีเทาที่อยู่นอกช่วง 0.0–1.0 ด้วย InvalidArgumentException
• กลยุทธ์ที่ทำงานซึ่งไม่ทำให้เกิดการเปลี่ยนแปลง Producer, Subject หรือลายน้ำ จะถูกปฏิเสธด้วย BrandingApplicationException แทนการปล่อยไบต์ที่ดูเหมือนแบบชำระเงิน
• หน้าที่ไม่มี /MediaBox ที่ใช้ได้ (ไม่มีหรือสืบทอดมา) จะถูกทำลายน้ำที่ค่าเริ่มต้น A4 ตาม ISO 216 คือ 595.276 × 841.890 จุด
• รองรับ /Contents ทั้งแบบอ้างอิงเดี่ยวและแบบอาร์เรย์ การอ้างอิงลายน้ำถูกต่อท้ายเป็นลำดับสุดท้ายเพื่อให้วาดอยู่ด้านบน หน้าที่ไม่มี /Contents จะได้รับหนึ่งรายการ
• ค่าสตริง Info วนกลับในรูปแบบเดิมของมัน คือ สตริงเลขฐานสิบหก (UTF-16BE) ยังคงเป็นเลขฐานสิบหก literal string ยังคงเป็น literal คีย์ที่ไม่มีจะถูกต่อท้าย และเข้ารหัสเป็นเลขฐานสิบหกเมื่อค่ามีอักขระที่ไม่ใช่ ASCII
• เอกสารที่เข้ารหัสจะถูกปฏิเสธ เพราะการเขียน string object ใหม่ภายใต้ /Encrypt จะต้องใช้คีย์การเข้ารหัสของเอกสาร
• ความล้มเหลวพกโค้ดที่เสถียร SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE) เพื่อให้ไปป์ไลน์ที่บริโภคสามารถทำ dead-letter และตรวจสอบผลลัพธ์ที่แสดงแบรนด์ไม่ได้
• โมดูลนี้ไม่ทำการดำเนินการทางการเข้ารหัส การตรวจสอบลายเซ็นของซองสิทธิ์การใช้งานเป็นหน้าที่ของระบบย่อยสิทธิ์การใช้งาน ดูเอกสารอ้างอิงเชิงลึก Licensing

ความสอดคล้อง

ข้อกล่าวอ้าง	มาตรฐาน	ข้อ
incremental update ต่อท้ายการเปลี่ยนแปลงที่ท้ายไฟล์และปล่อยเนื้อหาเดิมไว้ครบถ้วน	ISO 32000-2	§7.5.6
cross-reference section ของ update ครอบคลุมเฉพาะ object ที่เปลี่ยนแปลง และ trailer ที่เพิ่มเข้ามาพกรายการ Prev ที่ระบุตำแหน่ง cross-reference section ก่อนหน้า	ISO 32000-2	§7.5.6
literal string ถูกเขียนในวงเล็บ วงเล็บที่ไม่สมดุลและ reverse solidus ต้องมีการ escape	ISO 32000-2	§7.3.4.2

ทุกข้อเป็นการถอดความ NextPDF ไม่ได้คัดลอกข้อความเชิงบรรทัดฐาน NextPDF ไม่ได้อ้างการรับรองใด ๆ applicator เขียน incremental update ในรูปแบบ ISO 32000-2 ที่อ้างถึงเป็นคำแถลงความสามารถ มันไม่ใช่ writer ที่ได้รับการรับรองหรือตรวจสอบโดยอิสระ หน้านี้อธิบายพฤติกรรมในขณะรันไทม์เท่านั้น มันไม่มีการรับประกัน ไม่มีคำแถลงเกี่ยวกับสิทธิ์หรือผลทางกฎหมาย และไม่ถือเป็นคำแนะนำทางกฎหมาย ข้อกำหนดของการประเมินหรือการสมัครสมาชิกถูกกำหนดโดยข้อตกลงสิทธิ์การใช้งานเพียงอย่างเดียว

บันทึกการพัฒนา

• BrandingMode, BrandingStrategy, กลยุทธ์ทั้งสอง และ config พก @since 3.0.0; BrandingApplicator และ BrandingApplicationException พก @since 3.1.0
• ระบบย่อยไม่เรียกเครือข่าย applicator อ่านเฉพาะฟิลด์เชิงโครงสร้างที่มันเขียนใหม่ ได้แก่ สตริงใน Info dictionary, page dictionary และส่วนท้าย cross-reference
• ซองสิทธิ์การใช้งานเป็นอาร์ทิแฟกต์ที่ลงนามซึ่งรันไทม์ตรวจสอบลายเซ็นของผู้ออก การจัดเตรียม การต่ออายุ และการจัดเก็บสิทธิ์การใช้งานที่ปลอดภัยเป็นความรับผิดชอบของผู้ดำเนินการ
• ชนิดรูปธรรมทั้งหมดเป็น final; กลยุทธ์และ config เป็น readonly ด้วย สร้างอินสแตนซ์ config ใหม่เพื่อเปลี่ยนสไตล์ลายน้ำ
• BrandingStrategy::isActive() ที่คืนค่า false รับประกันค่า identity จากเมธอดอื่นทุกตัว ผู้เรียกอาจ short-circuit บนมันเพื่อประสิทธิภาพ
• สตรีมลายน้ำอ้างอิงชื่อทรัพยากร /helvetica Core ลงทะเบียนทรัพยากรนี้สำหรับการแสดงแบรนด์ของตัวเอง การผสานรวมที่ปิดการแสดงแบรนด์ของ Core ต้องแน่ใจว่าทรัพยากรนี้มีอยู่
• applicator ไม่คำนวณ digest ผู้เรียกต้อง re-digest ไบต์ที่มีแบรนด์ก่อนคอมมิตมัน
• รายละเอียดกลไกภายในอยู่ในเอกสารภายในของ repository ต้นทางและอยู่นอกขอบเขตของคู่มือนี้

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว public API ที่รองรับเท่านั้น เส้นทาง namespace ภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต

ดูเพิ่มเติม

• Branding — หน้าความสามารถสำหรับระบบย่อยการแสดงแบรนด์โหมดประเมิน
• Trial and Evaluation Branding — เรื่องราวการประเมินแบบครบวงจร
• Licensing — เอกสารอ้างอิงเชิงลึก
• ภาพรวม Enterprise