คู่มือนักพัฒนาสำหรับความเข้ากันได้กับ TCPDF

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

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

ใช้คู่มือนี้เมื่อคุณต้องดูแลโค้ดรูปแบบ TCPDF เดิม เพิ่มความครอบคลุมของอะแดปเตอร์ หรือวางแผนการย้ายระบบแบบเป็นขั้นตอนไปยัง API ของ NextPDF แบบเนทีฟ

ขอบเขตของสถาปัตยกรรม

เลเยอร์	เป็นเจ้าของโดย	ความรับผิดชอบ	อย่าใส่ไว้ที่นี่
แอปพลิเคชันแบบเดิม	แอปพลิเคชัน	ทำให้การเรียกใช้รูปแบบ TCPDF ที่มีอยู่ยังทำงานได้ระหว่างการย้ายระบบ	ฟีเจอร์ PDF ใหม่ที่ควรใช้ API ของ NextPDF แบบเนทีฟ
เชลล์ของอะแดปเตอร์	nextpdf/compat-legacy	เปิดเผยคลาสรูปแบบ TCPDF และสถานะความเข้ากันได้ที่ใช้ร่วมกัน	กลุ่มเมธอดขนาดใหญ่หรือตรรกะการแปลงค่า
เทรต Concern	nextpdf/compat-legacy	จัดกลุ่มตระกูลเมธอดแบบเดิม: ข้อความ ฟอนต์ รูปภาพ ความปลอดภัย ฟอร์ม และเพจ	นโยบายเอาต์พุตข้ามตระกูล
คลาส Bridge	nextpdf/compat-legacy	แปลงอาร์กิวเมนต์ ปลายทาง สี หน่วย และรูปแบบเดิม	พฤติกรรมเฉพาะทางธุรกิจ
เอนจินหลัก	nextpdf/nextpdf	สร้างเอกสารแบบเนทีฟ	ข้อรับประกันความเข้ากันได้แบบเดิม

วงจรชีวิตขณะรันไทม์

ขั้นตอน	พฤติกรรม	การดำเนินการของนักพัฒนา
Bootstrap	Bootstrap แบบเดิมที่เลือกใช้ได้จะเปิดเผยชื่อเพื่อความเข้ากันได้	ใช้เฉพาะในตำแหน่งที่โค้ดแบบเดิมคาดหวังสัญลักษณ์ของ TCPDF
การสร้างอ็อบเจกต์	อะแดปเตอร์จะแมปอาร์กิวเมนต์คอนสตรักเตอร์แบบเดิมไปยังค่ากำหนดของเอกสารหลัก	รักษาอินพุตของคอนสตรักเตอร์ให้เสถียรระหว่างการย้ายระบบ
การเรียกเมธอด	เมธอดที่รองรับจะแมปไปยังพฤติกรรมของ NextPDF ผ่าน Concern และ Bridge	ตรวจสอบความครอบคลุมของเมธอดก่อนสรุปว่าพฤติกรรมเทียบเท่ากัน
ฟีเจอร์ที่ไม่รองรับ	อะแดปเตอร์จะโยน Exception ด้านความเข้ากันได้อย่างชัดเจนสำหรับพฤติกรรมที่ไม่รองรับ	แทนที่การเรียกใช้หรือแยกไว้หลังโค้ดของแอปพลิเคชัน
เอาต์พุต	Bridge ของเอาต์พุตจะแมปพฤติกรรมปลายทางแบบเดิมไปยังเอาต์พุตของ NextPDF	ตรวจสอบความถูกต้องของชื่อไฟล์และรากพื้นที่จัดเก็บ

บัญชีรายการสำหรับการย้ายระบบ

เริ่มจากรวบรวมการเรียกเมธอดของ TCPDF ทุกครั้งในแอปพลิเคชันของคุณ จำแนกประเภทของการเรียกใช้แต่ละครั้งก่อนเปลี่ยนพฤติกรรมใด ๆ

การจำแนกประเภท	ความหมาย	การดำเนินการ
เมธอดของอะแดปเตอร์ที่รองรับ	เมธอดนี้มีบันทึกว่ารองรับและมีการทดสอบแล้ว	เก็บไว้ชั่วคราว แล้วจึงย้ายระบบเมื่อคุณแก้ไขส่วนนั้น
เมธอดของอะแดปเตอร์ที่รองรับบางส่วน	เมธอดนี้มีอยู่ แต่พฤติกรรมไม่ตรงกับ TCPDF แบบเดิมโดยสมบูรณ์	เพิ่มการทดสอบด้วยฟิกซ์เจอร์และตรวจสอบความถูกต้องของเอาต์พุตด้วยตนเอง
เมธอดที่ไม่รองรับอย่างชัดเจน	อะแดปเตอร์จะโยน Exception สำหรับความเข้ากันได้	แทนที่ด้วย NextPDF แบบเนทีฟหรือนำฟีเจอร์ออก
แรปเปอร์เฉพาะทางธุรกิจ	แอปพลิเคชันห่อหุ้มการเรียกใช้ TCPDF ไว้แล้ว	ย้ายระบบส่วนภายในของแรปเปอร์ก่อน
การเรียกใช้ที่เกี่ยวข้องกับการปฏิบัติตามข้อกำหนด	ลายเซ็น การเข้ารหัสลับ การทำแท็ก PDF/A การเข้าถึง หรือโฟลว์ใบแจ้งหนี้	ย้ายระบบไปยัง API ของ NextPDF แบบเนทีฟพร้อมการตรวจสอบเฉพาะทาง

รูปแบบการมีส่วนร่วมกับอะแดปเตอร์

เพิ่มการรองรับความเข้ากันได้ในตระกูลเมธอดที่เล็กที่สุดซึ่งเป็นเจ้าของพฤติกรรมนั้น

ประเภทของการเปลี่ยนแปลง	ตำแหน่งที่จะนำไปใช้งาน	การทดสอบที่จำเป็น
เมธอดเอาต์พุตข้อความ	Concerns\AdaptsTextOutput หรือ Concern ของฟอนต์	ฟิกซ์เจอร์แบบเดิมพร้อมการยืนยันเอาต์พุตแบบเนทีฟ
เมธอดเพจหรือระยะขอบ	Concern ของเพจ การกำหนดตำแหน่ง หรือระยะขอบ	การทดสอบการแปลงพิกัดและสถานะของเพจ
เมธอดรูปภาพหรือการวาด	Concern ของรูปภาพ การวาด สี หรือเกรเดียนต์	การทดสอบการตรวจสอบความถูกต้องของอินพุตและเอาต์พุตแบบ visual/structural
ปลายทางของเอาต์พุต	OutputBridge	การทดสอบการแมปปลายทางและเส้นทางที่ไม่ปลอดภัย
ฟีเจอร์ที่ไม่รองรับ	Exception factory หรือตารางความครอบคลุมของเมธอด	การทดสอบประเภทของ Exception และข้อความ

อย่าเพิ่มเมธอดขนาดใหญ่ลงในเชลล์ของอะแดปเตอร์โดยตรงเมื่อเทรต Concern เป็นเจ้าของตระกูลนั้น

รูปแบบการย้ายระบบแบบเนทีฟ

ใช้อะแดปเตอร์เพื่อทำให้โค้ดแบบเดิมเสถียร แล้วจึงย้ายเวิร์กโฟลว์ที่เสถียรไปยัง API แบบเนทีฟ

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

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

จุดขยายความสามารถ

จุดขยายความสามารถ	ใช้สำหรับ	ข้อจำกัด
AdaptationConfig	ควบคุมพฤติกรรมของอะแดปเตอร์ระหว่างการย้ายระบบ	คงค่าเริ่มต้นให้ชัดเจนและผ่านการตรวจทาน
เทรต Concern	จัดกลุ่มตระกูลเมธอด เช่น ข้อความ ฟอร์ม รูปภาพ หรือความปลอดภัย	เพิ่มเมธอดไปยัง Concern ที่เหมาะสม ไม่ใช่เชลล์ของอะแดปเตอร์
คลาส Bridge	แปลงรูปแบบอาร์กิวเมนต์แบบเดิมให้เป็นค่าของเอนจินหลัก	ครอบคลุมพฤติกรรมของ Bridge ด้วยการทดสอบการย้ายระบบ
CompatAdapterInterface	ชั้นนามธรรมระดับอะแดปเตอร์สำหรับเครื่องมือ	อย่าใช้แทนสัญญาของเอนจินหลักแบบเนทีฟในโค้ดใหม่
ตารางความครอบคลุมของเมธอด	บันทึกสถานะการรองรับสำหรับผู้พัฒนา	อัปเดตเมื่อสถานะการรองรับเปลี่ยนแปลง

เวิร์กโฟลว์การย้ายระบบ

1. ติดตั้งอะแดปเตอร์และรันชุดทดสอบแบบเดิมโดยไม่เปลี่ยนแปลง
2. เปิด ความครอบคลุมของเมธอด และจำแนกประเภทของทุกเมธอดที่ถูกเรียกใช้
3. แทนที่เมธอดที่ไม่รองรับก่อน
4. ย้ายเส้นทางที่มีปริมาณสูงหรือเกี่ยวข้องกับการปฏิบัติตามข้อกำหนดไปยัง API ของเอนจินหลักแบบเนทีฟ
5. เพิ่มความครอบคลุมด้วยฟิกซ์เจอร์สำหรับทุกตระกูลเมธอดที่ย้ายระบบแล้ว
6. นำชื่อแฝงของ Bootstrap ออกเมื่อไม่มีเอนทรีพอยต์ของแอปพลิเคชันใดต้องพึ่งพา

การจัดการความล้มเหลว

ความล้มเหลว	ตำแหน่งที่ควรจัดการ	การตอบสนองที่แนะนำ
เมธอดที่ไม่รองรับ	Exception ของอะแดปเตอร์	แทนที่การเรียกใช้หรือแยกออกไปไว้หลังอะแดปเตอร์ของแอปพลิเคชัน
เค้าโครงที่เทียบเท่ากันเพียงบางส่วน	การทดสอบการย้ายระบบและการตรวจทานด้วยสายตา	บันทึกความแตกต่างที่ยอมรับได้ก่อนการเปิดตัว
ปลายทางของเอาต์พุตที่ไม่ปลอดภัย	OutputBridge และนโยบายพื้นที่จัดเก็บของแอปพลิเคชัน	ปฏิเสธเส้นทางที่ไม่ปลอดภัยและเลือกใช้ API เอาต์พุตแบบเนทีฟ
ความไม่ตรงกันของฟีเจอร์ด้านความปลอดภัย	แผนการย้ายระบบแบบเนทีฟ	อย่าส่งมอบเอาต์พุตที่อยู่ภายใต้การกำกับดูแลด้วยพฤติกรรมที่มีไว้เพื่อความเข้ากันได้เท่านั้น
การชนกันของชื่อแฝงของ Bootstrap	Bootstrap ของแอปพลิเคชัน	นำชื่อแฝงระดับโกลบอลออกหรือจำกัดขอบเขตไว้ที่เอนทรีพอยต์แบบเดิม

ค่าเริ่มต้นที่ปลอดภัย

ส่วนงาน (Concern)	ค่าเริ่มต้น	เมื่อใดควรแทนที่
เมธอดที่ไม่รองรับ	โยน Exception อย่างชัดเจน	อย่าลดทอนค่านี้ในการใช้งานจริง
ค่าเริ่มต้นแบบเดิม	รวมศูนย์ไว้ใน LegacyDefaults	แทนที่เฉพาะสำหรับพฤติกรรมการย้ายระบบที่ทราบแล้วเท่านั้น
การแมปเอาต์พุต	ดำเนินการผ่าน OutputBridge	ใช้ API เอาต์พุตแบบเนทีฟหลังการย้ายระบบ
แหล่งความครอบคลุม	เพจความครอบคลุมของเมธอดและการทดสอบ	รันการตรวจสอบความครอบคลุมอีกครั้งหลังการอัปเกรดอะแดปเตอร์แต่ละครั้ง
โหมดเข้มงวด	เปิดใช้งานไว้ระหว่างการตรวจสอบการย้ายระบบ	ปิดใช้งานเฉพาะสำหรับช่วงความเข้ากันได้แบบเดิมที่มีการบันทึกไว้เท่านั้น

รายการตรวจสอบการทดสอบ

• เก็บฟิกซ์เจอร์แบบเดิมไว้สำหรับทุกตระกูลเมธอดที่ย้ายระบบแล้ว
• เพิ่มการทดสอบ NextPDF แบบเนทีฟหนึ่งรายการก่อนแทนที่เมธอดแบบเดิม
• ยืนยันว่าเมธอดที่ไม่รองรับโยน Exception ที่มีการบันทึกไว้
• เปรียบเทียบโครงสร้างของเอาต์พุตเมื่อความเท่ากันระดับไบต์แบบแม่นยำไม่ใช่เป้าหมายที่สมจริงของการย้ายระบบ
• รันการตรวจสอบความครอบคลุมของเมธอดหลังจากเพิ่มหรือเปลี่ยนเมธอดของอะแดปเตอร์
• เพิ่มการทดสอบเส้นทางพื้นที่จัดเก็บสำหรับทุกปลายทางของเอาต์พุตที่โค้ดแบบเดิมใช้