การแก้ปัญหา compat-legacy

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

ปัญหาส่วนใหญ่ระหว่างการย้ายระบบมักเกิดซ้ำในไม่กี่รูปแบบ รายการด้านล่างระบุอาการ สาเหตุ และวิธีแก้ไข เมื่อไม่แน่ใจเกี่ยวกับเมทอดใดเมทอดหนึ่ง ให้ตรวจสอบ /integrations/tcpdf-compat/method-coverage/ และเมทริกซ์ภายในรีโพที่เป็นแหล่งอ้างอิงที่เชื่อถือได้ docs/TCPDF_COVERAGE.md

เดิมกระบวนการหยุดเมื่อเกิดข้อผิดพลาดของ PDF แต่ตอนนี้มี exception ถูกปล่อยออกมา

อาการ โค้ดที่เคยหยุดเมื่อการเรนเดอร์ล้มเหลว ตอนนี้กลับโยน RuntimeException ที่ไม่ได้ถูกจับ และทำให้คำขอหรืองานจบด้วยข้อผิดพลาด

สาเหตุ ใน TCPDF รุ่นเดิม การเรียก Error() จะเรียก die() แต่อะแดปเตอร์ออกแบบให้โยน RuntimeException แทน เพื่อให้ระบบมองเห็นความล้มเหลวได้

วิธีแก้ไข ครอบจุดเริ่มการเรนเดอร์ด้วย try/catch แล้วแมป exception ให้เข้ากับสัญญาการจัดการข้อผิดพลาดของระบบ อย่านำพฤติกรรมของ die() กลับมา ดู /integrations/tcpdf-compat/production-usage/ § Failure handling

`new \TCPDF()` ยังคงชี้ไปยังไลบรารี TCPDF ตัวจริง

อาการ เปิดใช้งาน LegacyBootstrap::enableAliases() แล้ว แต่ผลลัพธ์ยังดูเหมือน TCPDF รุ่นเดิม หรือพฤติกรรมไม่เปลี่ยนแปลง

สาเหตุ enableAliases() จะลงทะเบียน alias เฉพาะเมื่อยังไม่มีคลาสชื่อเดียวกันอยู่ หาก tecnickcom/tcpdf ยังโหลดผ่าน autoload ได้ และคลาส \TCPDF ถูกโหลดก่อน ระบบจะข้าม alias และโค้ดจะยังใช้ TCPDF รุ่นเดิมต่อไป

วิธีแก้ไข ระหว่างการย้ายระบบ ให้ใช้การ import แบบระบุชัดเจนในแต่ละไฟล์ (use NextPDF\Compat\Tcpdf\TCPDF;) เพื่อให้ทุกจุดเรียกใช้ไม่กำกวม นำ tecnickcom/tcpdf ออกหลังการตรวจสอบผ่านแล้ว (ดู /integrations/tcpdf-compat/migration/ Stage 5) อย่ารันทั้งสองไลบรารีพร้อมเปิดใช้งาน global alias ในโปรเซสเดียวกัน

เมทอด “ทำงานได้” แต่พารามิเตอร์ที่ส่งเข้าไปถูกเพิกเฉย

อาการ การเรียกสำเร็จและสร้างไฟล์ Portable Document Format (PDF) ได้ แต่ตัวเลือกที่ส่งเข้าไป (ลิงก์รูปภาพ การจัดแนว จุดต่อนิ้ว (DPI) สีของบุ๊กมาร์ก …) ไม่ส่งผลใดๆ

สาเหตุ เมทอดนี้อยู่ในกลุ่มที่เพิกเฉยต่อค่าโดยไม่แจ้งเตือน เมทอดจะรับพารามิเตอร์ไว้เพื่อคงความเข้ากันได้ของซอร์สโค้ด แล้วละทิ้งพารามิเตอร์เหล่านั้น นี่เป็นพฤติกรรมที่ระบุไว้ในเอกสาร ไม่ใช่บั๊ก ดู /integrations/tcpdf-compat/method-coverage/ §2

วิธีแก้ไข รันการตรวจสอบในโหมดเข้มงวด (strict mode) เพื่อค้นหาทุกการเรียกในลักษณะนี้:

<?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('logo.png', 10, 10, 50, 0, '', 'https://example.com');
} catch (TcpdfNotImplementedException $e) {
    // Message lists every ignored parameter and a migration hint.
    echo $e->getMessage(), "\n";
}

จากนั้นนำพารามิเตอร์ออก หรือเรนเดอร์ใหม่ผ่าน API สมัยใหม่ ($pdf->getDocument()) ตามที่แสดงไว้ใน /integrations/tcpdf-compat/migration/ Stage 4

`MultiCell()` ส่งกลับค่าเป็น 1 เสมอ

อาการ โค้ดที่เลือกเส้นทางการทำงานตามค่าที่ส่งกลับจาก MultiCell() (เช่น เพื่อคำนวณความสูงที่ใช้หรือจำนวนบรรทัด) ทำงานผิดพลาด

สาเหตุ MultiCell() ของอะแดปเตอร์จะส่งกลับค่าตัวยึดเพื่อความเข้ากันได้คือ 1 ไม่ใช่จำนวนเซลล์หรือจำนวนบรรทัดที่เรนเดอร์ได้ ส่วน Write() ก็ส่งกลับ 0 เช่นเดียวกัน

วิธีแก้ไข อย่าใช้ค่าที่ส่งกลับเหล่านี้เป็นเงื่อนไขสำหรับแยกเส้นทางการทำงาน หากต้องการความสูงที่เรนเดอร์ได้ ให้คำนวณจาก getStringHeight() / getNumLines() หรือย้ายตรรกะนั้นไปยัง API สมัยใหม่

`setPDFVersion('1.4')` ไม่ได้สร้างไฟล์ PDF 1.4

อาการ ขอ PDF เวอร์ชันเก่ากว่า แต่ผลลัพธ์ยังคงเป็น PDF 2.0

สาเหตุ อะแดปเตอร์จะส่งออกเป็น PDF 2.0 เสมอ (ISO 32000-2) setPDFVersion() อยู่ในกลุ่มที่ไม่สามารถใช้งานได้ อะแดปเตอร์จะแจ้งเตือน (notice) แล้วทำงานต่อไป

วิธีแก้ไข นำการเรียกนี้ออก หากผู้บริโภคปลายทางต้องการ PDF เวอร์ชันเก่ากว่า ให้จัดการข้อกำหนดนั้นแยกต่างหาก อะแดปเตอร์ไม่สามารถลดเวอร์ชันเป้าหมายได้

`setSignature()` ไม่ทำอะไรเลย — PDF ไม่ถูกลงลายเซ็น

อาการ เรียก setSignature() พร้อมใบรับรองแล้ว แต่ PDF ที่ส่งออกไม่มีลายเซ็น

สาเหตุ เอนจินหลักไม่รองรับ setSignature() ผ่านอะแดปเตอร์นี้ ในโหมดเริ่มต้น เมทอดนี้จะไม่ทำงานใดๆ (no-op) ส่วนในโหมดเข้มงวดจะโยน exception

วิธีแก้ไข การลงลายเซ็นต้องใช้ NextPDF รุ่นเชิงพาณิชย์และ signature API สมัยใหม่ ดู /integrations/tcpdf-compat/security-and-operations/ § Digital signatures อย่าคาดหวังว่าการเรียก setSignature() รุ่นเดิมจะลงลายเซ็นให้เอกสารใดๆ ได้

`Output()` ทำให้การตอบสนอง HTTP หรือเอาต์พุตของ worker เสียหาย

อาการ มีไบต์ PDF ปรากฏในการตอบสนอง Hypertext Transfer Protocol (HTTP) หรือบันทึก (log) ของ worker มีไบต์ PDF ปะปนอยู่

สาเหตุ ใช้ปลายทางเอาต์พุตที่เขียนไปยังเส้นทางเอาต์พุต (I/D) ขณะที่ควบคุมการตอบสนองด้วยตนเอง อะแดปเตอร์ ไม่ สะท้อนเอาต์พุตไปยังบัฟเฟอร์ของคุณเหมือนที่ TCPDF รุ่นเดิมทำ แต่ I/D ยังคงสั่งให้เอนจินส่งเอาต์พุต

วิธีแก้ไข ใน worker และตัวจัดการที่คุณควบคุม ให้ใช้ Output($path, 'F') เพื่อเขียนไฟล์ หรือ Output($name, 'S') เพื่อรับไบต์แล้วส่งออกด้วยตนเอง tests/Unit/Compat/Tcpdf/Bridge/OutputBridgeTest.php ยืนยันว่าการแมปปลายทางไม่คำนึงถึงตัวพิมพ์ใหญ่และเล็ก และตัดช่องว่างออก:

โค้ด	ค่าที่ส่งกลับ	ผลข้างเคียง
`S`	ไบต์ PDF (`%PDF…`)	ไม่มี
`F`	สตริงว่าง	เขียนไฟล์
`E`	เนื้อหา MIME แบบ base64	ไม่มี
`FI` / `FD`	สตริงว่าง	เขียนไฟล์ แล้วจึงส่งเอาต์พุตของเอนจิน
`I` / `D` / ไม่ทราบ	สตริงว่าง	เอาต์พุตของเอนจิน (แสดงในหน้า/ดาวน์โหลด)

การตรวจสอบ PDF แบบเทียบไบต์ตรงตัวล้มเหลวหลังเปลี่ยนมาใช้

อาการ การทดสอบแบบ snapshot ที่เปรียบเทียบไบต์ PDF ดิบล้มเหลวทั้งหมด

สาเหตุ เอนจินมีการใช้งาน PDF 2.0 ของตนเองอย่างอิสระ เมทอดที่ส่งต่อไปยังเอนจินจะสร้างเอาต์พุตที่เรนเดอร์เข้ากันได้ แต่ไบต์จะแตกต่างกัน ซึ่งเป็นสิ่งที่คาดหมายได้

วิธีแก้ไข ปรับเส้นฐาน (baseline) ของการทดสอบใหม่ ให้ตรวจสอบเนื้อหาที่เรนเดอร์ได้ (ข้อความที่สกัดออกมา) โครงสร้าง (จำนวนหน้า ขนาดหน้า) หรือการตรวจสอบแบบ smoke (str_starts_with($bytes, '%PDF')) ดู /integrations/tcpdf-compat/migration/ Stage 4

ค่าคงที่ `K_` / `PDF_` รุ่นเดิมมีค่าผิด

อาการ เส้นทางที่กำหนดเองหรือค่าเริ่มต้นที่ตั้งผ่านค่าคงที่ไม่มีผล

สาเหตุ อะแดปเตอร์จะกำหนดค่าคงที่โดยอัตโนมัติเฉพาะเมื่อยังไม่มีการกำหนดไว้ และจะทำระหว่างการสร้างอินสแตนซ์ครั้งแรก หาก define() ของคุณทำงาน หลังจาก สร้างอะแดปเตอร์ตัวแรกแล้ว ค่าเริ่มต้นของอะแดปเตอร์จะมีผลไปแล้ว

วิธีแก้ไข กำหนดค่าคงที่ K_* / PDF_* ที่กำหนดเองทุกตัวใน bootstrap ก่อนสร้างอินสแตนซ์ของอะแดปเตอร์ใดๆ ดู /integrations/tcpdf-compat/configuration/ § Configuration resolution order

เวอร์ชันของเอนจินไม่ตรงกันขณะสร้างอินสแตนซ์

อาการ การสร้างอินสแตนซ์ล้มเหลว หรือพฤติกรรมเปลี่ยนไปอย่างไม่คาดคิดหลังอัปเดต dependency

สาเหตุ อะแดปเตอร์ต้องการ nextpdf/core ^3.0 หากเวอร์ชัน core ที่ resolve ได้อยู่นอกช่วงดังกล่าว จะไม่ได้รับการรองรับ

วิธีแก้ไข รัน composer show nextpdf/core แล้วปักหมุดเอนจินไว้ที่ ^3.0 ดู /integrations/tcpdf-compat/install/ § Verify the engine version

ข้อมูลอ้างอิงด่วนสำหรับการวินิจฉัย

คำถาม	ควรดูที่ใด
เมทอด X ทำอะไรจริงๆ ในที่นี้	ดูที่ /integrations/tcpdf-compat/method-coverage/ และเมทริกซ์ `docs/TCPDF_COVERAGE.md`
การเรียกใดทำให้พารามิเตอร์สูญหาย	การตรวจสอบในโหมดเข้มงวด (หน้านี้; /integrations/tcpdf-compat/migration/)
เพราะเหตุใดกระบวนการจึงไม่หยุดเมื่อเกิดข้อผิดพลาด	ดูที่ /integrations/tcpdf-compat/security-and-operations/ § Hardened behaviors
เพราะเหตุใดเอาต์พุตจึงไม่ถูกลงลายเซ็น / ไม่ใช่ PDF/A	ดูที่ /integrations/tcpdf-compat/security-and-operations/
ความขัดแย้งระหว่าง alias กับการ import แบบระบุชัดเจน	หน้านี้; /integrations/tcpdf-compat/boot-and-discovery/

ดูเพิ่มเติม

/integrations/tcpdf-compat/migration/ — การย้ายระบบแบบเป็นขั้นตอนที่ป้องกันปัญหาส่วนใหญ่ข้างต้น
/integrations/tcpdf-compat/method-coverage/ — ข้อมูลอ้างอิงพฤติกรรมรายเมทอด
/integrations/tcpdf-compat/boot-and-discovery/ — การลงทะเบียน alias และการหลีกเลี่ยงความขัดแย้ง
docs/TCPDF_COVERAGE.md — เมทริกซ์ความครอบคลุมที่เป็นแหล่งอ้างอิงที่เชื่อถือได้