ภาพรวมของ NextPDF compat-legacy

โดยสรุป

nextpdf/compat-legacy เป็น ทางเลือกที่เข้ากันได้กับ TCPDF หรือกล่าวให้ชัดคือ เลเยอร์ความเข้ากันได้ที่เปิดเผย public API ของ TCPDF 6.x บนเอนจิน Portable Document Format (PDF) 2.0 ของ NextPDF เลเยอร์นี้มีหน้าที่เพียงอย่างเดียว คือช่วยให้โค้ดที่พึ่งพา TCPDF 6.x อยู่แล้วรันบนเอนจิน NextPDF ได้โดยไม่ต้องเขียนใหม่ คุณจึงย้ายระบบทีละไฟล์ได้ แทนที่จะต้องย้ายทั้งหมดในคราวเดียว

เลเยอร์นี้ไม่ใช่ fork ของ TCPDF และไม่ใช่โคลนเชิงพฤติกรรมที่รับประกันความเหมือนได้ เลเยอร์นี้เป็นการพัฒนาแบบอิสระที่ยังคงลายเซ็นการเรียก (call signature) ของ TCPDF ไว้ คำอธิบายที่แม่นยำคือ เลเยอร์นี้ครอบคลุม 94 เมท็อดจากเมท็อด TCPDF 6.x ที่สำรวจไว้ประมาณ 120 เมท็อด โดยใช้การมอบหมาย (delegation) โดยตรง ส่วนเมท็อดที่เหลือมีความแตกต่างเชิงพฤติกรรมตามที่ระบุไว้ในเอกสาร (ดู /integrations/tcpdf-compat/method-coverage/)

สิ่งที่เลเยอร์นี้เป็น

ตัวช่วยในการย้ายระบบ แพ็กเกจนี้อยู่ในตระกูล compat ของ NextPDF และช่วยให้คุณเลิกใช้ไลบรารี PDF รุ่นเก่า แต่ไม่ได้มีไว้เป็นการพึ่งพาถาวร ให้มองว่าเป็นโครงชั่วคราวที่คุณจะถอดออกเมื่อย้ายไปใช้ API สมัยใหม่แล้ว
อะแดปเตอร์ที่ระดับพื้นผิว API อะแดปเตอร์นี้จัดเตรียมชื่อคลาส ชื่อเมท็อด ลำดับพารามิเตอร์ และค่าเริ่มต้นของ TCPDF เวอร์ชัน 6.2.13 แล้วมอบหมายการเรียกไปยังอินสแตนซ์ NextPDF\Core\Document หนึ่งตัว
การพัฒนาแบบอิสระในรูปแบบ clean-room แพ็กเกจนี้ไม่คัดลอกหรือแปลงซอร์สโค้ดของ TCPDF อาร์ติแฟกต์จากการบิลด์ ข้อมูลฟอนต์ หรือผลงานรูปแบบอื่นที่มีลิขสิทธิ์ แพ็กเกจนี้ใช้ชื่อ TCPDF เพื่อระบุความสามารถในการทำงานร่วมกันเท่านั้น ข้อความอย่างเป็นทางการอยู่ในไฟล์ NOTICE ของแพ็กเกจ

สิ่งที่เลเยอร์นี้ไม่ใช่

เลเยอร์นี้ไม่ใช่ “drop-in replacement” ที่ให้เอาต์พุตเหมือนกันทุกไบต์ สำหรับเมท็อดที่ถูกมอบหมาย ผลลัพธ์ที่มองเห็นจะเข้ากันได้ แต่ไบต์ของ PDF ที่เรนเดอร์ออกมาจะแตกต่างกัน เพราะเบื้องล่างเป็นการพัฒนา PDF 2.0 ที่แยกเป็นอิสระ
เลเยอร์นี้ไม่ได้ “เข้ากันได้กับ TCPDF 100%” มีชุดเมท็อดที่ระบุไว้อย่างชัดเจน ซึ่งรับพารามิเตอร์รุ่นเก่าที่เอนจินไม่รองรับ หรือไม่ดำเนินการใดเลย เมท็อดเหล่านี้ถูกระบุไว้เป็นรายการและผ่านการทดสอบแล้ว โปรดดู /integrations/tcpdf-compat/method-coverage/
เลเยอร์นี้ไม่ใช่ผลิตภัณฑ์สำหรับการลงนามหรือการเก็บถาวรโดยตัวเอง ลายเซ็นดิจิทัลและการสอดคล้องตามมาตรฐานการเก็บถาวร PDF/A จำกัดไว้สำหรับ NextPDF รุ่นเชิงพาณิชย์ เอกสารนี้ไม่ได้กล่าวอ้างใดๆ เกี่ยวกับการรับรอง การรับประกัน หรือลายเซ็นที่มีผลทางกฎหมาย

เหตุใดจึงควรย้ายระบบผ่านเลเยอร์ความเข้ากันได้

การเขียนจุดเรียก TCPDF ใหม่ทั้งหมดในแอปพลิเคชันขนาดใหญ่มีความเสี่ยงและส่งมอบเป็นช่วงได้ยาก เลเยอร์ความเข้ากันได้ช่วยให้คุณสามารถ:

สลับการพึ่งพา แล้วรันชุดทดสอบที่มีอยู่เพื่อดูว่าส่วนใดทำงานได้โดยไม่ต้องเปลี่ยนแปลง
ใช้ strict mode เป็นการตรวจสอบที่แสดงรายการจุดทั้งหมดซึ่งไม่สามารถจำลองพฤติกรรมของ TCPDF ได้อย่างเที่ยงตรง
ทยอยย้ายจุดเรียกเหล่านั้นไปยัง API สมัยใหม่ของ NextPDF เพื่อให้แอปพลิเคชันยังคงพร้อมส่งมอบได้ตลอดกระบวนการ

สถานะปลายทางคือการใช้ API NextPDF\Core\Document สมัยใหม่ และถอดเลเยอร์ความเข้ากันได้ออก ดูกลยุทธ์ฉบับเต็มได้ที่ /integrations/tcpdf-compat/migration/

สิ่งที่คุณจะได้รับบนเอนจิน NextPDF

เมื่ออะแดปเตอร์มอบหมายการเรียก TCPDF การเรียกนั้นจะทำงานบนเอนจิน PDF 2.0 (ISO 32000-2) ซึ่งรองรับการเข้ารหัสลับแบบ standard-handler ด้วย Advanced Encryption Standard (AES)-256 และมีความปลอดภัยด้านชนิดข้อมูลระดับ PHPStan Level 10 ทั่วทั้งอะแดปเตอร์ เอาต์พุตจะถูกเขียนเป็น PDF 2.0 เสมอ อะแดปเตอร์ไม่สามารถปรับลดเป้าหมายไปยัง PDF เวอร์ชันเก่ากว่าได้ (ดู /integrations/tcpdf-compat/method-coverage/ §4)

อะแดปเตอร์เสริมความปลอดภัยให้กับพฤติกรรมเดิมหลายอย่างของ TCPDF 6.2.13:

พฤติกรรมเดิม	พฤติกรรมของอะแดปเตอร์
`Error()` เรียก `die()` และยุติโปรเซสอย่างเงียบๆ	`Error()` โยน `RuntimeException` จึงสังเกตได้และดักจับได้
เมท็อด HTML ที่สามารถรัน PHP จากมาร์กอัปได้	ช่องทางดังกล่าวถูกปิดใช้งาน มาร์กอัปจึงไม่สามารถสั่งให้รัน PHP ได้
`Output()` ส่งเอาต์พุตโดยตรงและอาจทำให้บัฟเฟอร์เอาต์พุตของเวิร์กเกอร์เสียหายได้	เอาต์พุตจะผ่านบริดจ์ปลายทางที่ปลอดภัย
การเรียกซ้ำของ header/footer ที่ไม่มีการป้องกัน	มีการป้องกันการเรียกซ้ำ

ขอบเขตและรุ่นของผลิตภัณฑ์

เลเยอร์ความเข้ากันได้รวมอยู่ในชุดแจกจ่าย core (nextpdf/compat-legacy ซึ่งต้องใช้ nextpdf/core ^3.0) การเข้ารหัสลับผ่าน standard handler ใช้งานได้ใน core ลายเซ็นดิจิทัลและการสอดคล้องตามมาตรฐานการเก็บถาวร PDF/A ต้องใช้ NextPDF รุ่นเชิงพาณิชย์ อะแดปเตอร์เปิดเผยจุดเข้าถึงไว้ แต่เส้นทาง core ไม่ใช่ผลิตภัณฑ์สำหรับการลงนาม ดูข้อความที่แม่นยำได้ที่ /integrations/tcpdf-compat/security-and-operations/

ขั้นตอนถัดไป

/integrations/tcpdf-compat/install/ — ติดตั้งแพ็กเกจและตรวจสอบการเชื่อมโยงเอนจิน
/integrations/tcpdf-compat/quickstart/ — สร้างเอกสารแรกที่รันได้พร้อมการทดสอบรองรับ
/integrations/tcpdf-compat/method-coverage/ — ดูรายละเอียดที่แม่นยำว่าเมท็อด TCPDF แต่ละตัวทำงานอย่างไรในเลเยอร์นี้
/integrations/tcpdf-compat/migration/ — วางแผนกลยุทธ์การย้ายระบบทีละไฟล์
/integrations/tcpdf-compat/configuration/ — ตั้งค่า strict mode และค่ากำหนดของอะแดปเตอร์
/integrations/tcpdf-compat/production-usage/ — รันอะแดปเตอร์ภายใต้โหลดและในเวิร์กเกอร์
/integrations/tcpdf-compat/security-and-operations/ — ทบทวนการเข้ารหัสลับ สถานะการลงนาม และการเพิ่มความปลอดภัย
/integrations/tcpdf-compat/troubleshooting/ — แก้ไขข้อผิดพลาดที่พบบ่อยในการย้ายระบบ
/integrations/tcpdf-compat/integration/ / /integrations/tcpdf-compat/boot-and-discovery/ — เชื่อมต่อฟาซาดเข้ากับแอปพลิเคชันและลงทะเบียน global class alias

ดูเพิ่มเติม

docs/TCPDF_COVERAGE.md — เมทริกซ์ความครอบคลุมอย่างเป็นทางการ (ในรีโพ)
ไฟล์ NOTICE ของแพ็กเกจ — ข้อความระบุการพัฒนาแบบอิสระ