Pro รุ่น

Projection

ภาพรวมโดยสังเขป

Projection แจง content stream ของ PDF เป็นรายการโทเค็นแบบแบนและส่งออก content stream ใหม่จากโทเค็นเหล่านั้น การส่งออกต้องมีการประกาศเจตนาอย่างชัดแจ้ง โมดูลนี้ไม่ใช่โปรแกรมแก้ไข PDF อเนกประสงค์

หมายเหตุ “Projection” ในที่นี้หมายถึงการฉายโทเค็นของ content stream ไม่ใช่การฉายพิกัดหรือการฉายเชิงภูมิสารสนเทศ สำหรับฟีเจอร์เชิงภูมิสารสนเทศ ดูโมดูล Geo

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

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

ไม่มีแฟล็กสิทธิ์ใช้งานแยกต่างหากรายฟีเจอร์ อาร์กิวเมนต์ ProjectionIntent ที่จำเป็นเป็นตัวเกตการส่งออกที่ระดับ API ไม่ใช่สวิตช์สิทธิ์ใช้งาน

การติดตั้ง

composer require nextpdf/pro:^3

โค้ดอยู่ภายใต้เนมสเปซ NextPDF\Pro\Projection

ภาพรวมเชิงแนวคิด

ContentProjectionWriter มอบการดำเนินการแบบ static สามอย่าง:

tokenize() แจง content stream เป็นรายการโทเค็นแบบแบนที่เรียงลำดับ นี่เป็นแบบอ่านอย่างเดียวและไม่ต้องใช้เจตนา
emit() เขียน content stream ใหม่จากรายการโทเค็น (ที่อาจถูกแก้ไข) ต้องใช้ ProjectionIntent
roundTrip() แปลงเป็นโทเค็นแล้วส่งออกใหม่โดยไม่มีการเปลี่ยนแปลง สำหรับการตรวจสอบความถูกต้อง

เอาต์พุตในเชิงแนวคิดเป็น content stream ใหม่ ไม่ใช่สำเนาที่แก้ไขของต้นฉบับ ตัวส่งออกทำให้ช่องว่างและความคิดเห็นเป็นปกติแต่คงลำดับ operator และค่า operand ไว้ตรงเป๊ะ enum เจตนามีเพียงสองกรณีพอดี ได้แก่ การทำให้สะอาด (การปิดบัง) และการฝังแบบ steganographic และจงใจไม่มีกรณีทั่วไป เพื่อให้การวิเคราะห์เชิงสถิตตรวจจับการใช้งานที่ไม่ได้ตั้งใจได้

เหตุใดจึงทำงานเช่นนี้

Projection ปฏิเสธที่จะเป็นโปรแกรมแก้ไข PDF อเนกประสงค์ การส่งออกสร้าง content stream ใหม่ขึ้นมาจากรายการโทเค็นแบบแบน ต้นฉบับจึงไม่เคยถูกเปลี่ยนแปลงในที่เดิม แบบจำลองทางเดียวนี้คือสิ่งที่ทำให้การปิดบังน่าเชื่อถือ โทเค็นที่ถูกลบจะหายไปจากเอาต์พุต ไม่ใช่ถูกทาทับ emit() จึงเรียกร้อง ProjectionIntent ที่ชัดแจ้ง และ enum เสนอเพียงการทำให้สะอาดและการฝังแบบ steganographic เท่านั้น ไม่มีกรณีทั่วไป การวิเคราะห์เชิงสถิตจึงสามารถชี้การส่งออกใด ๆ ที่ขาดจุดประสงค์ที่ประกาศไว้และเป็นที่รู้จักได้ การออกแบบนี้แลกความสะดวกในการแก้ไขกับการรับประกันว่าเจตนาที่ทำลายล้างจะมองเห็นได้เสมอที่จุดเรียกใช้

ที่มาของการออกแบบ: Redaction is not a black rectangle

สัญญาพฤติกรรม

tokenize($contentStream) คืนรายการโทเค็นที่ครอบคลุมสตริง ชื่อ ตัวเลข อาเรย์ พจนานุกรม บูลีน null และ operator
emit($tokens, $intent) ต้องมีเจตนาที่ชัดแจ้ง ระบบชนิดบังคับใช้สิ่งนี้ที่จุดเรียกใช้
เอาต์พุตของ roundTrip() ไม่เหมือนกันในระดับไบต์กับอินพุต แต่ลำดับ operator และค่า operand ตรงกัน
ตัวส่งออกจัดรูปแบบตัวเลขเพื่อคงความแตกต่างระหว่างจำนวนเต็มกับ float และ escape สตริงตัวอักษรใหม่
เจตนาที่ประกาศไว้สองอย่างคือการทำให้สะอาด (การดำเนินการปิดบังที่ทำลายล้างและย้อนกลับไม่ได้) และการฝังแบบ steganographic

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

ต่อไปนี้สะท้อน public API ที่จัดทำเอกสารไว้ repository ไม่ได้มาพร้อมตัวอย่างที่รันได้สำหรับโมดูลนี้

use NextPDF\Pro\Projection\ContentProjectionWriter;

$tokens = ContentProjectionWriter::tokenize($contentStream);

ตัวอย่างโค้ด — การใช้งานจริง

use NextPDF\Pro\Projection\ContentProjectionWriter;
use NextPDF\Pro\Projection\ProjectionIntent;

$tokens = ContentProjectionWriter::tokenize($contentStream);

// Validate first: a clean round-trip must hold before any modification.
$check = ContentProjectionWriter::roundTrip($contentStream);

// Apply your modification to $tokens, then emit with a declared intent.
$output = ContentProjectionWriter::emit($tokens, ProjectionIntent::Sanitization);

กรณีขอบและข้อควรระวัง

รัน roundTrip() และยืนยันว่าผ่านก่อนที่คุณจะไว้วางใจลำดับการแก้ไขแล้วส่งออก ให้ถือว่า round-trip ที่ล้มเหลวเป็นเงื่อนไขหยุด
เจตนาการทำให้สะอาดเป็นแบบย้อนกลับไม่ได้ เนื้อหาที่ถูกลบไม่สามารถกู้คืนจากเอาต์พุตได้
ตัวส่งออกทำให้ช่องว่างเป็นปกติและตัดความคิดเห็นทิ้ง การเปรียบเทียบในระดับไบต์กับต้นฉบับจึงจะต่างกันแม้สำหรับ round-trip ที่ไม่ได้แก้ไข

ประสิทธิภาพ

Tokenize และ emit เป็นเชิงเส้นตามความยาวของ content stream ตัวแปลงโทเค็นจำกัดการอ่าน octal escape และการจัดการสตริงฐานสิบหก ไม่มีตัวเลขปริมาณงานที่เผยแพร่ วัดผลด้วย content stream ที่เป็นตัวแทน

หมายเหตุด้านความปลอดภัย

อาร์กิวเมนต์เจตนาที่จำเป็นป้องกันการใช้งานในทางที่ผิดเป็นโปรแกรมแก้ไขทั่วไป เจตนาการทำให้สะอาดเป็นแบบทำลายล้างและย้อนกลับไม่ได้ ให้ตรวจสอบ round-trip ก่อนและยืนยันเอาต์พุตที่ปิดบังแล้วก่อนการแจกจ่าย โมดูลนี้ไม่บันทึกเนื้อหา

การเป็นไปตามข้อกำหนด

การแปลงเป็นโทเค็นเป็นไปตามแบบแผนเชิงคำศัพท์และ content-stream ใน ISO 32000-2 ซอร์สอธิบายข้อที่เกี่ยวข้องไว้ คลังข้อมูล RAG ไม่พร้อมใช้งานในเวลาเขียน หน้านี้จึงไม่อ้างตัวระบุข้อภายนอกและจำกัดคำแถลงการเป็นไปตามข้อกำหนดไว้เฉพาะพฤติกรรมที่ตรวจสอบโดยการทดสอบของโมดูล

หมายเหตุขอบเขตของ Enterprise

Enterprise ไม่เปลี่ยนพฤติกรรมของ Projection Enterprise เพิ่มฟีเจอร์ความเป็นส่วนตัวและการปฏิบัติตามข้อกำหนดระดับสูงกว่าซึ่งจัดทำเอกสารแยกต่างหาก ฟีเจอร์เหล่านั้นไม่จำเป็นสำหรับการใช้ API ของ projection

ทางเลือกสำรองของ Core

ไม่มีสิ่งเทียบเท่าใน Core หากไม่มี Pro ผู้เรียกใช้ต้องสร้างตัวแปลงโทเค็นของ content stream เอง แบบจำลองการฉายที่ถูกเกตด้วยเจตนาเป็นส่วนเพิ่มเฉพาะของ Pro

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

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