ความครอบคลุมของเมธอด TCPDF ใน NextPDF compat-legacy

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

nextpdf/compat-legacy เป็นเลเยอร์ความเข้ากันได้ ไม่ใช่ฟอร์กของ TCPDF และไม่ใช่โคลนเชิงพฤติกรรมที่รับประกันได้ เลเยอร์นี้เปิดเผยชื่อเมธอดสาธารณะ ลำดับพารามิเตอร์ และค่าเริ่มต้นของ TCPDF 6.x บนเอนจินหลักของ NextPDF การเรียกส่วนใหญ่แมปไปยังการดำเนินการ Document ของ NextPDF โดยตรง มีเพียงส่วนน้อยที่รับพารามิเตอร์แบบเดิมซึ่ง NextPDF ไม่รองรับ หรือไม่มีผลใด ๆ

หน้านี้สรุปผลการตรวจสอบรายเมธอดสำหรับผู้อ่าน เมทริกซ์การครอบคลุมที่เป็นทางการและผ่านการตรวจสอบด้วยการทดสอบอยู่ในที่เก็บโค้ดที่ docs/TCPDF_COVERAGE.md หากหน้านี้กับเมทริกซ์ในที่เก็บโค้ดไม่ตรงกัน ให้ถือเมทริกซ์ในที่เก็บโค้ดเป็นเกณฑ์ เพราะชุดทดสอบยืนยันรายการเหล่านั้น

ใช้หน้านี้เพื่อหาคำตอบหนึ่งข้อก่อนการย้ายระบบ: สำหรับเมธอด TCPDF แต่ละตัวที่ฐานโค้ดของคุณเรียกใช้ อะแดปเตอร์ทำสิ่งใดจริง ๆ?

สรุปการครอบคลุม

การตรวจสอบสำรวจเมธอดสาธารณะของ TCPDF 6.x ประมาณ 120 ตัว และจัดแต่ละเมธอดไว้ในหนึ่งในสี่หมวดหมู่อย่างชัดเจน

หมวดหมู่	จำนวน	ความหมายสำหรับคุณ
Mirrored — มอบหมายทั้งหมด	94	การเรียกแมปไปยังเมธอด `Document` ของ NextPDF โดยตรง พฤติกรรมเข้ากันได้กับพารามิเตอร์ที่มีเอกสารกำกับ
Silent-ignore — บางส่วน	15	เมธอดทำงานและสร้างเอาต์พุต แต่พารามิเตอร์ TCPDF อย่างน้อยหนึ่งตัวไม่มีผล นี่คือความต่างด้านพฤติกรรมที่มีเอกสารกำกับ
Unimplemented — เนื้อเมธอดเป็น no-op	4	เมธอดมีอยู่เพื่อให้ซอร์สยังเข้ากันได้ แต่ไม่ทำสิ่งใด
ไม่เกี่ยวข้อง	7	เมธอด TCPDF นี้ไม่มีผลต่อเอาต์พุต PDF จึงถูกแยกออกโดยเจตนา
เมธอด modern-API drift ที่เพิ่มเข้ามา	17	เมธอด Document ของ NextPDF v5.1+ ที่เปิดเผยบนอะแดปเตอร์เพื่อให้โค้ดที่ใช้ API ปนกันยังคอมไพล์ได้ เมธอดเหล่านี้ไม่มีตัวเทียบเท่าใน TCPDF 6.x

ตัวเลขเหล่านี้มาจาก docs/TCPDF_COVERAGE.md §Summary ชุดทดสอบตรวจสอบเมทริกซ์ผ่าน tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php และ tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php ตามลำดับ

หมายเหตุเรื่องถ้อยคำ แพ็กเกจนี้ไม่ได้อ้างว่าเป็น “drop-in replacement” หรือ “100% TCPDF compatible” โดยครอบคลุม 94 เมธอดจากที่สำรวจ ~120 เมธอดของ TCPDF ด้วยการมอบหมายโดยตรง เมธอดที่เหลือมี ความต่างด้านพฤติกรรมที่มีเอกสารกำกับตามที่อธิบายไว้ด้านล่าง คำอธิบายที่ถูกต้อง คือ ทางเลือกที่เข้ากันได้กับ TCPDF ซึ่งมี พื้นผิวความเข้ากันได้ที่ทราบและผ่านการทดสอบ แล้ว

หมายเหตุเรื่องการนับเมธอด

อะแดปเตอร์สร้างขึ้นจาก concern trait ที่รับผิดชอบหน้าที่เดียวจำนวน 25 ตัว (src/Compat/Tcpdf/Concerns/) ซึ่งเปิดเผยเมธอดสาธารณะรวมทั้งหมด 273 ตัว รวมถึงเมธอดวงจรชีวิตและ escape-hatch จำนวนเล็กน้อยบนคลาส TCPDF เอง หมวดหมู่การครอบคลุมด้านบนนับเมธอดที่แตกต่างกันบนพื้นผิว API ของ TCPDF 6.x (~120) ไม่ใช่จำนวนเมธอดสาธารณะทั้งหมดของอะแดปเตอร์ ตัวเลขสองชุดวัดคนละเรื่อง: ความครอบคลุมของพื้นผิว API และขนาดของพื้นผิวที่พัฒนา หากไฟล์ README.md ของแพ็กเกจระบุจำนวน trait หรือจำนวนเมธอดน้อยกว่า ให้ถือว่า docs/TCPDF_COVERAGE.md และหน้านี้เป็นเกณฑ์ที่เป็นทางการ บทสรุปใน README จัดทำก่อนมี trait AdaptsDriftV51

1. เมธอดแบบ mirrored — การมอบหมายที่เข้ากันได้

เก้าสิบสี่เมธอดแมปไปยังอินสแตนซ์ NextPDF\Core\Document ที่อยู่เบื้องล่างโดยตรง ชื่อ TCPDF แบบ PascalCase แมปไปยังชื่อ NextPDF แบบ camelCase ในจุดที่เอนจินใช้ camelCase อะแดปเตอร์รองรับทั้งสองรูปแบบการสะกดเพื่อความเข้ากันได้ทั้งไปข้างหน้าและย้อนหลัง

กลุ่มตัวแทน (ตารางเต็ม: docs/TCPDF_COVERAGE.md §1):

ส่วนของ TCPDF	เมธอดตัวอย่าง	Trait ของอะแดปเตอร์
วงจรชีวิต	`Output()`, `Close()`, `getPDFData()`	`AdaptsLifecycle`
หน้า	`AddPage()`, `getNumPages()`, `deletePage()`	`AdaptsPageManagement`
ข้อความ	`Cell()`, `MultiCell()`, `Write()`, `Text()`, `Ln()`	`AdaptsTextOutput`
ฟอนต์	`SetFont()`, `SetFontSize()`, `AddFont()`	`AdaptsFonts`
สี	`SetTextColor()`, `SetDrawColor()`, `SetFillColor()`	`AdaptsColors`
การวาด	`Line()`, `Rect()`, `Circle()`, `Polygon()`, `Arrow()`	`AdaptsDrawing`
การแปลงรูป	`Rotate()`, `Scale()`, `Translate()`, `Skew()`, `Mirror*()`	`AdaptsTransforms`
การนำทาง	`AddLink()`, `Annotation()`, `addTOC()`	`AdaptsNavigation`

สำหรับเมธอดเหล่านี้ พฤติกรรมที่สังเกตได้เข้ากันได้กับ TCPDF 6.x สำหรับพารามิเตอร์ที่ NextPDF มีเอกสารกำกับ อะแดปเตอร์ไม่ได้ยืนยันว่าเอาต์พุต PDF จะเหมือนกันทุกไบต์ เอนจินที่อยู่เบื้องล่างเป็นการพัฒนา PDF 2.0 แบบอิสระ ดังนั้นไบต์จึงต่างกันได้แม้ผลลัพธ์ที่มองเห็นจะเทียบเท่ากัน หากการทดสอบของคุณยืนยันไบต์ PDF ที่แน่นอนแทนเนื้อหาที่เรนเดอร์ ให้คาดหวังว่าจะต้องตั้งค่าฐานใหม่ให้กับ assertion เหล่านั้น ดู /integrations/tcpdf-compat/migration/ สำหรับกลยุทธ์การตั้งค่าฐานใหม่ที่แนะนำ

2. เมธอดแบบ silent-ignore — ความแตกต่างด้านพฤติกรรมที่มีเอกสารกำกับ

เมธอด 15 ตัวนี้ทำงานและสร้างเอาต์พุต แต่มีพารามิเตอร์ TCPDF อย่างน้อยหนึ่งตัวที่รับไว้เพื่อให้ซอร์สยังเข้ากันได้ แล้วจึงถูกเพิกเฉย อ่านส่วนนี้ก่อนการย้ายระบบ การเรียกเหล่านี้ไม่ล้มเหลว แต่ทำงานได้น้อยกว่า TCPDF ต้นฉบับอย่างเงียบ ๆ

เมธอด TCPDF	พารามิเตอร์ที่ถูกเพิกเฉย	ทางเลือกที่เข้ากันได้
`Image()`	พารามิเตอร์ type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs	เมธอด `image()` ของ NextPDF รับ file, x, y, width, height สำหรับภาพที่คลิกได้ ให้วาดภาพก่อน แล้วเพิ่ม `Document::link()` ทับบนสี่เหลี่ยมเดียวกัน ไม่รองรับการมาสก์ภาพและภาพสำรอง
`writeHTML()`	พารามิเตอร์ ln, fill, reseth, cell, align	เมธอด `writeHtml()` ของ NextPDF รองรับเฉพาะเนื้อหาเท่านั้น ให้ห่อ HTML ไว้ในบล็อกที่จัดตำแหน่งผ่าน API สมัยใหม่เพื่อควบคุมเค้าโครง
`writeHTMLCell()`	พารามิเตอร์ border (string form), ln, fill, reseth, autopadding	ความกว้าง ความสูง ตำแหน่ง และเส้นขอบแบบบูลีนได้รับการรองรับ ส่วนเค้าโครงเซลล์ที่ซับซ้อนกว่านั้นไม่มีการแมป
`ImageEps()`	พารามิเตอร์ link, useBoundingBox, align, palign, border, fitonpage, fixoutvals	ตำแหน่งและขนาดเท่านั้น
`ImageSVG()`	พารามิเตอร์ link, align, palign, border, fitonpage	ตำแหน่งและขนาดเท่านั้น
`SetProtection()`	พารามิเตอร์ mode (non-zero), pubkeys (non-empty)	NextPDF ใช้ AES-256 สำหรับตัวจัดการมาตรฐานเสมอ สำหรับการเข้ารหัสลับด้วยใบรับรอง ให้ใช้ `setPublicKeyEncryption()` สมัยใหม่ที่เปิดเผยบนอะแดปเตอร์ (ดู /integrations/tcpdf-compat/security-and-operations/)
`Bookmark()`	พารามิเตอร์ style, color, x, isNamedDest	ชื่อเรื่อง ระดับ และตำแหน่งแกน y ได้รับการรองรับ
`setDestination()`	พารามิเตอร์ page, x	ชื่อและตำแหน่งแกน y ได้รับการรองรับ
`Link()`	พารามิเตอร์ spaces	การติดตามช่องว่างภายในของ TCPDF ไม่มีตัวเทียบเท่าในเอนจิน
`Annotation()`	พารามิเตอร์ option keys beyond Subtype, spaces	ชนิด ตำแหน่ง และข้อความได้รับการรองรับ
`SetLineStyle()`	พารามิเตอร์ dash-pattern detail beyond width	คุณสมบัติเส้นหลักได้รับการแมป
`setAlpha()`	การแมป blend-mode บางส่วน	ชื่อ blend-mode บางชื่อไม่มีตัวเทียบเท่าในเอนจิน
`Polycurve()`	รายการพารามิเตอร์ทั้งหมด	เป็น no-op ในโหมดเริ่มต้น ไม่มีตัวเทียบเท่าในเอนจิน
`PieSectorXY()`	รายการพารามิเตอร์ทั้งหมด	การแมปบางส่วน (เส้นจากจุดศูนย์กลางถึงขอบต่างกัน)
`RoundedRectXY()`	รัศมีแยกแต่ละมุม	รัศมีมุมแบบสม่ำเสมอเท่านั้น

วิธีที่อะแดปเตอร์เปิดเผยความต่างเหล่านี้ขึ้นอยู่กับโหมดเข้มงวด (ดู /integrations/tcpdf-compat/configuration/) เมื่อปิดโหมดเข้มงวด ซึ่งเป็นค่าเริ่มต้นที่เข้ากันได้ย้อนหลัง การเรียกเหล่านี้จะลดทอนการทำงานอย่างเงียบ ๆ เมื่อเปิดโหมดเข้มงวด ทุกการเรียกที่เพิกเฉยพารามิเตอร์จะโยน TcpdfNotImplementedException พร้อมรายการพารามิเตอร์ที่ถูกเพิกเฉยอย่างครบถ้วนและคำใบ้สำหรับการย้ายระบบ โหมดเข้มงวดเป็นเครื่องมือตรวจสอบ ไม่ใช่การตั้งค่าสำหรับโปรดักชัน

การออกแบบโหมดเข้มงวดยึดหลักการที่ว่าผู้เรียกต้อง สังเกตได้เมื่อเจตนาของตนไม่ได้รับการตอบสนอง OWASP ASVS 5.0 §16.5.3 ระบุว่าแอปพลิเคชันควรล้มเหลวอย่างนุ่มนวลและปลอดภัย และป้องกันสภาวะ fail-open การสูญเสียพารามิเตอร์อย่างเงียบ ๆ เป็น กับดักด้านประสบการณ์ของนักพัฒนามากกว่าจะเป็นช่องโหว่ แต่หลักการ ล้มเหลวอย่างชัดแจ้งเดียวกันก็ยังใช้ได้ สรุปย่อของข้อกำหนดที่ปักหมุดไว้อยู่ใน citations ใน front-matter ของหน้า

3. เมธอดแบบ unimplemented — เนื้อเมธอดเป็น no-op

เมธอดสี่ตัวมีอยู่เพื่อให้ซอร์สรุ่นเดิมคอมไพล์ได้ แต่เนื้อเมธอดไม่ทำสิ่งใด เมื่อเปิดโหมดเข้มงวด สามตัวจะโยน TcpdfNotImplementedException ตัวที่สี่ (Open()) เป็น no-op ที่ปลอดภัยโดยเจตนาและไม่เคยโยนข้อยกเว้น เพราะคุณสามารถนำออกจากโค้ดรุ่นเดิมได้อย่างปลอดภัยเสมอ

เมธอด TCPDF	พฤติกรรม	สิ่งที่ใช้แทน
`setSignature()`	เป็น no-op (ไม่จัดเก็บสิ่งที่นำไปใช้ได้) โยนข้อยกเว้นในโหมดเข้มงวด	การลงลายเซ็นดิจิทัลต้องใช้รุ่นเชิงพาณิชย์ของ NextPDF ใช้ signature API สมัยใหม่กับอ็อบเจกต์ค่า `CertificateInfo` ดู /integrations/tcpdf-compat/security-and-operations/
`addEmptySignatureAppearance()`	เป็น no-op โยนข้อยกเว้นในโหมดเข้มงวด	อยู่ภายใต้แนวทางสำหรับรุ่นเชิงพาณิชย์เดียวกับ `setSignature()`
`endPage()`	เป็น no-op โยนข้อยกเว้นในโหมดเข้มงวด	NextPDF จัดการวงจรชีวิตของหน้าโดยอัตโนมัติ นำการเรียกออก
`Open()`	เป็น no-op ที่ปลอดภัย ไม่เคยโยนข้อยกเว้น	NextPDF เปิดเอกสารโดยอัตโนมัติ การนำการเรียกออกปลอดภัยเสมอ

การลงลายเซ็นไม่พร้อมใช้งานในเอนจินหลักผ่านอะแดปเตอร์นี้ อะแดปเตอร์เปิดเผยจุดเข้าใช้งาน signature สมัยใหม่ที่มอบหมายไปยังเอนจิน การรองรับลายเซ็นพื้นฐานถูกกำกับไว้สำหรับรุ่นเชิงพาณิชย์ เอกสารนี้ไม่ได้อ้างสิ่งใดเกี่ยวกับโปรไฟล์ลายเซ็นแบบ long-term-validation หรือแบบประทับเวลาสำหรับรุ่นใด ๆ ดู /integrations/tcpdf-compat/security-and-operations/ สำหรับถ้อยคำที่แน่นอนและระมัดระวัง

4. เมธอดที่ไม่เกี่ยวข้อง

เมธอด TCPDF เจ็ดตัวไม่มีผลต่อเอาต์พุต PDF และถูกแยกออกโดยเจตนา คุณสามารถเรียกใช้เมธอดเหล่านี้ได้อย่างปลอดภัย

เมธอด TCPDF	เหตุผลที่แยกออก
`setDocCreationTimestamp()` / `setDocModificationTimestamp()`	สถานะถูกเก็บไว้บนอะแดปเตอร์ แต่ไม่ได้เชื่อมต่อกับเมตาดาทา XMP ของเอกสาร ไม่ปรากฏในเอาต์พุต
`setSRGBmode()`	การจัดการสีของ NextPDF เป็นอิสระจากแฟล็กนี้
`setPDFVersion()`	NextPDF เลือกเวอร์ชัน PDF จากโปรไฟล์ conformance/output ของตน ไม่มี setter โดยตรง อะแดปเตอร์ออกประกาศแจ้งและทำงานต่อ
`setDocInfoUnicode()`	NextPDF เป็น Unicode เสมอ แฟล็กนี้เป็น no-op โดยการออกแบบ
`setDefaultMonospacedFont()`	ไม่มีตัวเทียบเท่าในเอนจิน ใช้การจัดสไตล์ HTML/CSS แทน
`setFontSubsetting()`	NextPDF ทำ subset ฟอนต์ที่ฝังไว้เสมอ แฟล็กนี้จึงเปิดอยู่เสมอโดยพฤตินัย

เวอร์ชัน PDF ถูกกำหนดตายตัวโดยเอนจิน เอาต์พุตถูกเขียนเป็น PDF 2.0 (ISO 32000-2) ISO 32000-2 §7.5.2 ระบุว่าตัวเขียนที่สอดคล้องตามมาตรฐานต้องระบุเวอร์ชันของเอกสาร — ในส่วนหัวของไฟล์หรือในรายการ Version ของแคทาล็อก — เป็น 2.0 และยังระบุด้วยว่าการบันทึกไฟล์ไม่ทำให้เวอร์ชันของไฟล์ลดลง สิ่งนี้ตรงกับพฤติกรรมของอะแดปเตอร์: การเรียกเช่น setPDFVersion('1.4') ไม่สามารถกำหนดเป้าหมายเป็นเวอร์ชัน PDF ที่เก่ากว่าผ่านอะแดปเตอร์นี้ได้ สรุปย่อของข้อกำหนดที่ปักหมุดไว้อยู่ใน citations ใน front-matter ของหน้า

5. เมธอด modern-API drift

เมธอดสิบเจ็ดตัวจาก NextPDF core v5.1+ ถูกเปิดเผยบนอะแดปเตอร์ (trait AdaptsDriftV51) เพื่อให้โค้ดที่ผสม TCPDF API กับ API สมัยใหม่ยังคอมไพล์ได้ เมธอดเหล่านี้ไม่มีตัวเทียบเท่าใน TCPDF 6.x ตัวอย่าง: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode() ให้ถือว่าเมธอดเหล่านี้เป็น API สมัยใหม่ ไม่ใช่ส่วนหนึ่งของสัญญาความเข้ากันได้ของ TCPDF

6. คำแนะนำเรื่องการเลิกใช้และการใช้สิ่งทดแทน

หากโค้ดของคุณเรียก…	สถานะ	ทำสิ่งนี้แทน
`Error()`	พฤติกรรมเปลี่ยนแปลง (เข้มงวดขึ้น)	อะแดปเตอร์แทนที่ `die()` ของ TCPDF ด้วยการโยน `RuntimeException` ให้ห่อการเรียกที่เสี่ยงไว้ใน `try`/`catch` อย่าพึ่งพาการสิ้นสุดของกระบวนการ
`setPDFVersion()`	ไม่เกี่ยวข้อง	นำออก เอาต์พุตเป็น PDF 2.0 เสมอ
`setUserRights()`	เลิกใช้ใน PDF 2.0	นำออก การเรียกออกประกาศแจ้ง `E_USER_DEPRECATED` และถูกเพิกเฉย
`setSignature()`	ยังไม่ได้พัฒนาในเอนจินหลัก	ย้ายไปใช้ signature API สมัยใหม่บนรุ่นเชิงพาณิชย์
`Image(...)` ที่มีพารามิเตอร์เพิ่มเติม	เพิกเฉยอย่างเงียบ (Silent-ignore)	ลดเหลือ file, x, y, w, h เพิ่ม `Document::link()` สำหรับภาพที่คลิกได้
`endPage()` / `Open()`	ยังไม่ได้พัฒนา / no-op	นำออก

7. ขั้นตอนการย้ายระบบอย่างปลอดภัย

ติดตั้งแพ็กเกจและรันชุดทดสอบที่มีอยู่เดิมของคุณกับอะแดปเตอร์โดยไม่ต้องเปลี่ยนแปลงโค้ด ดู /integrations/tcpdf-compat/install/ และ /integrations/tcpdf-compat/quickstart/
เปิดโหมดเข้มงวดในการรันตรวจสอบเฉพาะ (ไม่ใช่ในโปรดักชัน): $pdf->setStrictMode(true); รวบรวม TcpdfNotImplementedException ทุกตัว แต่ละตัวระบุพารามิเตอร์ที่ถูกเพิกเฉยที่แน่นอนและคำใบ้สำหรับการย้ายระบบ
สำหรับจุดที่โยนข้อยกเว้นแต่ละจุด ให้เลือกว่าจะตัดพารามิเตอร์ที่ถูกเพิกเฉยออกหรือย้ายการเรียกนั้นไปยัง API สมัยใหม่ผ่าน $pdf->getDocument() แทน
ตั้งค่าฐานใหม่ให้กับการทดสอบใด ๆ ที่ยืนยันไบต์ PDF ที่แน่นอน ให้ยืนยันที่เนื้อหาที่เรนเดอร์หรือคุณสมบัติเชิงโครงสร้างแทน
ปิดโหมดเข้มงวดและนำเส้นทางโค้ดที่ตรวจสอบแล้วไปใช้งาน คงงาน CI โหมดเข้มงวดเป็นระยะไว้เพื่อจับการถดถอยเมื่อคุณรีแฟกเตอร์

ขั้นตอนแบบเต็มพร้อมโค้ด: /integrations/tcpdf-compat/migration/.

ดูเพิ่มเติม

docs/TCPDF_COVERAGE.md — เมทริกซ์การครอบคลุมที่เป็นทางการและผ่านการตรวจสอบด้วยการทดสอบ (ในที่เก็บโค้ด)
/integrations/tcpdf-compat/migration/ — กลยุทธ์การย้ายระบบจาก TCPDF ไปยัง NextPDF แบบครบวงจร
/integrations/tcpdf-compat/configuration/ — โหมดเข้มงวดและการกำหนดค่าอะแดปเตอร์
/integrations/tcpdf-compat/security-and-operations/ — ท่าทีด้านการเข้ารหัสลับและลายเซ็น
/integrations/tcpdf-compat/integration/ — การเชื่อมต่ออะแดปเตอร์เข้ากับแอปพลิเคชัน
/integrations/tcpdf-compat/boot-and-discovery/ — การลงทะเบียน class-alias และการเปิดเผยฟาซาด