ข้อมูลอ้างอิง API สำหรับความเข้ากันได้ของ TCPDF

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

แพ็กเกจ nextpdf/compat-legacy เปิดเผยคลาสหลักหนึ่งคลาสคือ NextPDF\Compat\Tcpdf\TCPDF ซึ่งทำตาม application programming interface (API) สาธารณะของ TCPDF 6.x แต่เรนเดอร์ด้วยเอนจิน NextPDF สมัยใหม่ นอกจากนี้ยังมี API surface สนับสนุนขนาดเล็ก ได้แก่ LegacyBootstrap สำหรับ alias คลาสระดับโกลบอล พื้นผิวการกำหนดค่า AdaptationConfig/LegacyDefaults คลาส bridge ภายในสำหรับ output การสร้างออบเจกต์ สี หน่วย และรูปแบบหน้า รวมถึง exception ด้านความเข้ากันได้ ใช้แพ็กเกจนี้เป็นเครื่องมือช่วยย้ายระบบ ไม่ใช่ dependency ถาวร ตารางความครอบคลุมของเมท็อดคือแหล่งข้อมูลสถานะเมท็อด legacy ฉบับครบถ้วน หน้านี้บันทึกเฉพาะ surface ที่โค้ดแอปพลิเคชันควรพึ่งพาโดยตั้งใจเท่านั้น

เริ่มที่นี่: หากเพิ่งเริ่มใช้แพ็กเกจนี้ ให้สร้าง NextPDF\Compat\Tcpdf\TCPDF เรียกคำสั่ง TCPDF ตามปกติ (AddPage(), SetFont(), Cell()) แล้วปิดท้ายด้วย Output($name, $dest) คลาสนี้เป็นจุดเริ่มต้นของเกือบทุกอย่างในส่วนต่อไปนี้ สำหรับตัวอย่างเริ่มต้นที่รันได้ โปรดดู งานทั่วไป

งานทั่วไป

งานเหล่านี้คือส่วนของแพ็กเกจที่ใช้งานบ่อยที่สุด แต่ละบล็อกผ่านการตรวจสอบกับซอร์สของ adapter แล้ว และรันได้ตามที่แสดง

สร้างไฟล์ Portable Document Format (PDF) ด้วยคำสั่ง TCPDF ที่คุ้นเคย แล้วเก็บผลลัพธ์เป็นสตริงสำหรับคิว การตอบสนอง HTTP หรือพื้นที่จัดเก็บ:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetTitle('Invoice 1234');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$bytes = $pdf->Output('invoice.pdf', 'S');

สิ่งที่ทำ: สร้างเอกสาร PDF 2.0 ผ่าน adapter ที่มีรูปทรงแบบ TCPDF และคืนค่าไบต์ดิบ (%PDF...) เนื่องจากปลายทาง 'S' ส่งผ่าน OutputBridge ไปยัง Document::getPdfData() แทนการ echo จึงใช้ภายใน worker หรือ controller ได้อย่างปลอดภัย

ลงทะเบียน alias ระดับโกลบอลหนึ่งครั้งในช่วง boot เพื่อให้โค้ด new \TCPDF(...) ที่มีอยู่เดิมรันได้โดยไม่ต้องแก้ซอร์ส:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/legacy.pdf', 'F');

สิ่งที่ทำ: enableAliases() ลงทะเบียน \TCPDF (รวมถึงเฮลเปอร์ \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES) แบบ idempotent เฉพาะเมื่อชื่อเหล่านั้นยังไม่ได้ถูกกำหนดไว้ก่อนเท่านั้น จากนั้นโค้ด legacy เดิมจะรันบน adapter ได้โดยไม่ต้องเปลี่ยนแปลง

ตรวจสอบการย้ายระบบโดยแสดงพารามิเตอร์ทั้งหมดของ TCPDF ที่ตามปกติ adapter จะละเว้นอย่างเงียบ ๆ:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter
}

สิ่งที่ทำ: เมื่อใช้ setStrictMode(true) การเรียกที่ไม่สามารถจำลองพฤติกรรมของ TCPDF ได้จะโยน TcpdfNotImplementedException และระบุชื่อทุกพารามิเตอร์ที่ถูกละเว้น วิธีนี้เปลี่ยนการลดทอนแบบเงียบ ๆ ให้เป็นรายการงานสำหรับการย้ายระบบ ให้รันเฉพาะในรอบการตรวจสอบเท่านั้น ห้ามรันในระบบจริงโดยเด็ดขาด

Adapter หลัก

ตารางนี้คือ surface มาตรฐานของ adapter ใช้ค้นหาคลาสที่สร้างอินสแตนซ์ (TCPDF) เมท็อด strict-mode และ escape hatch ของคลาส รวมถึง contract ที่คลาสนี้ implement

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
`NextPDF\Compat\Tcpdf\TCPDF`	พารามิเตอร์ constructor เป็นไปตามรูปทรง TCPDF แบบ legacy ผ่าน `ConstructorBridge`	สร้าง adapter ที่รองรับโดยมีเอกสาร NextPDF อยู่เบื้องหลัง	`TCPDF`	exception จากการตรวจสอบ constructor หรือคุณสมบัติที่ไม่รองรับ	ใช้ระหว่างการย้ายระบบ ไม่ใช่สำหรับโค้ด NextPDF แบบเนทีฟใหม่
`TCPDF::getDocument()`	ไม่มี	คืนค่าเอกสาร NextPDF ที่อยู่เบื้องหลัง	`NextPDF\Core\Document`	ไม่คาดว่าจะมี	ใช้เป็น escape hatch สำหรับโค้ดย้ายระบบที่ต้องผสมการเรียกแบบ legacy กับแบบเนทีฟเข้าด้วยกัน
`TCPDF::getUnitConverter()`	ไม่มี	คืนค่าตัวแปลงที่สร้างจากหน่วยแบบ legacy	`UnitConverter`	ไม่คาดว่าจะมี	ใช้สำหรับการวินิจฉัยการย้ายระบบ ไม่ใช่โค้ดแอปพลิเคชันตามปกติ
`TCPDF::setStrictMode(bool $enabled)`	แฟล็ก strict-mode	เปิดหรือปิดการล้มเหลวอย่างชัดเจนสำหรับพฤติกรรมความเข้ากันได้ที่ไม่รองรับ	`static`	ไม่คาดว่าจะมี	ให้เปิดไว้ระหว่างการตรวจสอบการย้ายระบบ
`TCPDF::isStrictMode()`	ไม่มี	คืนค่าแฟล็ก strict-mode ปัจจุบัน	`bool`	ไม่คาดว่าจะมี	มีประโยชน์ในการยืนยันผลของการทดสอบ
`TCPDF` เมท็อดแบบ legacy	แตกต่างกันไปตามเมท็อด	เมท็อดที่รองรับจะแมปไปยังการเรียกของเอกสารหลัก ส่วนเมท็อดที่ไม่รองรับจะล้มเหลวอย่างชัดเจน	แตกต่างกันไปตามเมท็อด	`TcpdfNotImplementedException` หรือ `UnsupportedFeatureException`	ตรวจสอบ ความครอบคลุมของเมท็อด ก่อนพึ่งพาเมท็อดใด
`CompatAdapterInterface::getDocument()`	ไม่มี	เมท็อด contract ที่ `TCPDF` implement	`Document`	ไม่คาดว่าจะมี	ให้เครื่องมือเข้าถึงเอกสารเนทีฟได้
`CompatAdapterInterface::Output(string $name = '', string $dest = '')`	ชื่อไฟล์และปลายทางแบบ legacy	มอบหมายให้ output bridge	`string`	ข้อผิดพลาดในการเขียนของแกนหลักหรือข้อผิดพลาดปลายทางที่ไม่รองรับ	สะท้อน output แบบ legacy ของ TCPDF โดย `TCPDF::Output` ที่เป็นรูปธรรมจะจัดหาค่าเริ่มต้น `'doc.pdf'`/`'I'`

กลุ่มเมท็อดแบบ legacy

ตารางนี้แมปกลุ่มเมท็อดของ TCPDF ที่ adapter ครอบคลุม ใช้สแกนหาการเรียกแบบ legacy ก่อนตรวจสอบสถานะที่แน่นอนในตารางความครอบคลุมของเมท็อด

กลุ่ม	สัญลักษณ์ที่เป็นตัวแทน	พฤติกรรมเริ่มต้น	หมายเหตุ
วงจรชีวิตและ output	`Open()`, `Close()`, `Output()`, `getPDFData()`	รักษาวงจรชีวิตของเอกสารในรูปทรงแบบ TCPDF บนเอกสารเนทีฟ	ควรใช้ API output แบบเนทีฟหลังจากย้ายระบบแล้ว
เมทาดาทา	`SetTitle()`, `SetAuthor()`, `SetSubject()`, `SetKeywords()`, `SetCreator()`	แมปตัวตั้งค่าเมทาดาทาไปยังเอกสารเบื้องหลัง	ให้คงการ normalize เมทาดาทาไว้ในโค้ดแอปพลิเคชัน
หน้าและการกำหนดตำแหน่ง	`AddPage()`, `setPage()`, `lastPage()`, `GetX()`, `SetXY()`	แปลงหน่วยและพิกัดแบบ legacy เป็นการดำเนินการกับหน้าแบบเนทีฟ	ตรวจสอบการกำหนดตำแหน่งแบบสัมบูรณ์ด้วยสายตาหลังการย้ายระบบ
ระยะขอบและเค้าโครง	`SetMargins()`, `SetAutoPageBreak()`, `setCellPaddings()`, `getMargins()`	เก็บสถานะความเข้ากันได้และแมปค่าที่รองรับ	พฤติกรรมการขึ้นหน้าใหม่ที่ซับซ้อนของ TCPDF อาจต้องตรวจสอบด้วยตนเอง
ฟอนต์และข้อความ	`SetFont()`, `AddFont()`, `Cell()`, `MultiCell()`, `Write()`, `Text()`	ส่งการดำเนินการกับข้อความทั่วไปไปยัง API ฟอนต์และข้อความแบบเนทีฟ	ตรวจสอบพฤติกรรม CJK และการเข้ารหัสด้วยฟอนต์ที่ใช้งานจริง
HTML	`writeHTML()`, `writeHTMLCell()`, `fixHTMLCode()`	ส่ง HTML ที่รองรับไปยังไปป์ไลน์ HTML แบบเนทีฟ	ตัวเรนเดอร์เนทีฟไม่ใช่โคลน HTML ของ TCPDF ที่สมบูรณ์
รูปภาพและการวาด	`Image()`, `Line()`, `Rect()`, `Circle()`, `SetDrawColor()`	แมปการดำเนินการกราฟิกที่รองรับผ่าน concern ของ adapter	รูปแบบเวกเตอร์หรือรูปแบบพิเศษที่ไม่รองรับจะล้มเหลวอย่างชัดเจน
การนำทางและคำอธิบายประกอบ	`Bookmark()`, `AddLink()`, `SetLink()`, `Annotation()`	รักษาการเรียกด้านการนำทางทั่วไปไว้เมื่อมีการแมป	ตรวจสอบความถูกต้องของ outline และลิงก์ที่สร้างขึ้น
ความปลอดภัยและลายเซ็น	`SetProtection()`, `setSignature()`, `setTimeStamp()`, `setUserRights()`	เชื่อมการเรียกความปลอดภัยแบบ legacy ที่รองรับไปยังคุณสมบัติเนทีฟ	ให้ถือว่า output ด้านวิทยาการเข้ารหัสลับเป็นเกตการตรวจสอบยืนยันแยกต่างหาก
ฟอร์ม เทมเพลต และการแปลง	`TextField()`, `startTemplate()`, `StartTransform()`, `Rotate()`, `Scale()`	implement ส่วนย่อยที่รองรับ และล้มเหลวอย่างชัดเจนสำหรับพฤติกรรมที่ไม่รองรับ	ตรวจสอบการเรียกแต่ละครั้งเทียบกับความครอบคลุมของเมท็อดก่อนนำไปใช้งานจริง

Bootstrap และการกำหนดค่า

ใช้ตารางนี้เมื่อเชื่อมต่อ adapter เข้ากับเส้นทาง boot ของแอปพลิเคชัน ลงทะเบียน alias ระดับโกลบอล หรือเลือกระหว่างค่าคงที่แบบ legacy กับ AdaptationConfig สมัยใหม่

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
`LegacyBootstrap::enableAliases()`	ไม่มี	ลงทะเบียน alias ด้านความเข้ากันได้หนึ่งครั้ง	`void`	ข้อผิดพลาดของ autoload หรือสภาพแวดล้อม	ใช้เฉพาะเมื่อโค้ด legacy คาดว่าชื่อ TCPDF จะมีอยู่ในระดับโกลบอล
`LegacyBootstrap::isRegistered()`	ไม่มี	รายงานว่ามีการลงทะเบียน alias แล้วหรือไม่	`bool`	ไม่คาดว่าจะมี	มีประโยชน์ในการทดสอบ bootstrap
`LegacyBootstrap::resetForTesting()`	ไม่มี	ล้างสถานะการลงทะเบียนเพื่อการทดสอบ	`void`	ไม่คาดว่าจะมี	เฮลเปอร์สำหรับการทดสอบเท่านั้น
`AdaptationConfig`	แฟล็กของ adapter และตัวควบคุมการย้ายระบบ	ใช้ค่าเริ่มต้นของแพ็กเกจเมื่อไม่ได้ระบุ	`AdaptationConfig`	ค่าตัวเลือกที่ไม่ถูกต้อง	ให้ระบุการกำหนดค่าอย่างชัดเจนระหว่างการตรวจสอบการย้ายระบบ
`AdaptationConfig::fromLegacyConstants()`	ไม่มี	อ่านค่าคงที่แบบ legacy ที่รู้จักและสร้างออบเจกต์การกำหนดค่า	`AdaptationConfig`	ค่าคงที่แบบ legacy ที่ไม่ถูกต้อง	เฮลเปอร์ช่วงเปลี่ยนผ่านสำหรับแอปพลิเคชัน legacy ขนาดใหญ่
`LegacyDefaults`	ไม่มี	ให้ค่าเริ่มต้นแบบ legacy	ค่าเริ่มต้น	ไม่คาดว่าจะมี	จุดศูนย์กลางสำหรับค่าเริ่มต้นด้านความเข้ากันได้

Bridge และเฮลเปอร์

คลาสการแปลงภายในเหล่านี้ขับเคลื่อน adapter ใช้ตารางนี้เมื่อมีส่วนร่วมในการเพิ่มความครอบคลุมของ adapter หรือเมื่อวินิจฉัยว่าอาร์กิวเมนต์แบบ legacy ถูกแปลอย่างไร สำหรับโค้ดแอปพลิเคชันประจำวัน ควรใช้ surface สาธารณะของ adapter

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
`ConstructorBridge`	รายการอาร์กิวเมนต์ของ constructor แบบ legacy	normalize ตัวเลือกแบบ legacy เป็นการกำหนดค่าของ NextPDF	ข้อมูล constructor	ค่าอาร์กิวเมนต์แบบ legacy ที่ไม่ถูกต้อง	adapter ใช้งานภายใน
`CellParameterAdapter`	พารามิเตอร์เซลล์ของ TCPDF	แมปอาร์กิวเมนต์แบบระบุตำแหน่งของ legacy เป็นตัวเลือกการจัดวางข้อความของแกนหลัก	พารามิเตอร์ที่ปรับแล้ว	มิติหรือการจัดแนวที่ไม่ถูกต้อง	ควรใช้เมท็อดของแกนหลักแบบเนทีฟในโค้ดใหม่
`OutputBridge::dispatch(Document $document, string $filename, string $dest)`	เอกสารเนทีฟ ชื่อไฟล์ และปลายทางแบบ legacy	แมปพฤติกรรม inline/download/save ไปยัง API output ของ NextPDF	`string`	ข้อผิดพลาดในการเขียนของแกนหลัก ปลายทางที่ไม่รองรับ	ตรวจสอบความถูกต้องของชื่อไฟล์และ root ของพื้นที่จัดเก็บก่อน output
`OutputBridge::resolveDestination(string $dest)`	รหัสปลายทางแบบ legacy	แปลงปลายทางเป็นปลายทาง output แบบเนทีฟ	`OutputDestination`	ข้อผิดพลาดปลายทางที่ไม่รองรับ	รวมศูนย์การแมปปลายทางไว้ที่เดียว
`ColorTranslator`	อาร์กิวเมนต์สีของ TCPDF	normalize รูปแบบสีแบบ legacy	ค่าสีของแกนหลัก	ค่าสีที่ไม่ถูกต้อง	ใช้โดย concern ของสีและการวาด
`PageFormatResolver`	อินพุตรูปแบบหน้าแบบ legacy	แมปชื่อที่รู้จักไปยังขนาดหน้าของแกนหลัก	ค่ารูปแบบหน้า	รูปแบบที่ไม่รู้จัก	ใช้ขนาดหน้าแบบเนทีฟที่ระบุชัดเจนหลังการย้ายระบบ
`UnitConverter`	ค่าการวัดและหน่วยแบบ legacy	แปลงเป็นหน่วยของแกนหลัก	ค่าตัวเลข	หน่วยที่ไม่ถูกต้อง	ช่วยรักษาพฤติกรรมเค้าโครงแบบ legacy

ข้อยกเว้น

ใช้ตารางนี้เมื่อการเรียกเพื่อย้ายระบบล้มเหลวอย่างชัดเจน ตารางนี้แยก “not implemented” ออกจากความล้มเหลวแบบ “known but unsupported” และแสดงเส้นทางการกู้คืน

สัญลักษณ์	ความหมาย	การกู้คืน
`TcpdfNotImplementedException`	adapter จงใจไม่ implement เมท็อด legacy ที่ร้องขอ	แทนที่การเรียกด้วย API NextPDF แบบเนทีฟ หรือนำ dependency ออก
`TcpdfNotImplementedException::forSilentIgnore()`	การเรียกแบบ legacy ที่เดิมจะถูกละเว้น แต่ถูกเปิดเผยเพื่อความชัดเจนระหว่างการย้ายระบบ	ตัดสินใจว่าพฤติกรรม no-op ที่ชัดเจนยอมรับได้หรือไม่
`TcpdfNotImplementedException::forUnimplemented()`	การเรียกแบบ legacy ไม่มีเส้นทาง adapter ที่ implement ไว้	แทนที่การเรียก หรือแยกการเรียกไว้หลังโค้ดการย้ายระบบ
`UnsupportedFeatureException`	คุณสมบัติแบบ legacy เป็นที่รู้จัก แต่ไม่รองรับภายในขอบเขตของ adapter	ตรวจสอบคำแนะนำการย้ายระบบ และแยกคุณสมบัติไว้หลัง adapter ของแอปพลิเคชัน
`UnsupportedFeatureException::forMethod()`	สร้างข้อผิดพลาดคุณสมบัติที่ไม่รองรับเฉพาะเมท็อด	ใช้เมื่อมีส่วนร่วมด้านความเข้ากันได้เพื่อรักษาข้อความแสดงความล้มเหลวให้สอดคล้องกัน

หมายเหตุการพัฒนา

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