การบูตและการตรวจพบ compat-legacy ของ NextPDF

โดยสรุป

nextpdf/compat-legacy ให้ใช้ NextPDF\Compat\Tcpdf\TCPDF ซึ่งเป็น facade ที่เข้ากันได้กับ TCPDF และส่งงานต่อไปยังเอนจิน NextPDF นี่คือ เลเยอร์ความเข้ากันได้ ไม่ใช่โคลนแบบ drop-in เลเยอร์นี้ส่งต่อการเรียกใช้โดยตรงให้ 94 เมธอดจากเมธอด TCPDF 6.x ที่สำรวจไว้ราว 120 เมธอด เมธอดที่เหลือมีความแตกต่างด้านพฤติกรรมตามที่ระบุไว้ในเอกสาร ดู /integrations/tcpdf-compat/method-coverage/

ในการออกแบบนี้ ไม่มีการเชื่อมโยงระดับ global ระหว่าง autoload การ require แพ็กเกจนี้จะไม่สร้างคลาส \TCPDF ระดับ global โดยค่าเริ่มต้น คุณต้องเลือกใช้ alias ระดับ global อย่างชัดเจน หรือในระหว่างการย้ายข้อมูล ทางที่เหมาะกว่าคือ import คลาสอะแดปเตอร์แบบรายไฟล์

วิธีเปิดเผย facade ของ TCPDF

facade เป็นคลาสที่ autoload ด้วยมาตรฐาน PHP Standard Recommendation 4 (PSR-4):

รายการ	ค่า
คลาส facade	`NextPDF\Compat\Tcpdf\TCPDF`
คำนำหน้า PSR-4	`NextPDF\Compat\Tcpdf\` แมปกับ `src/Compat/Tcpdf/`
contract ร่วม	`NextPDF\Compat\Contracts\CompatAdapterInterface`
ช่องทางฉุกเฉิน	`TCPDF::getDocument()` คืนค่าอ็อบเจกต์ `NextPDF\Core\Document` ที่ถูกห่อหุ้มไว้

คลาสนี้ตั้งใจออกแบบให้ ไม่เป็น final ผู้ใช้ TCPDF แบบเดิมมักสร้างคลาสย่อยจาก TCPDF เพื่อ override Header() และ Footer() และอะแดปเตอร์ยังคงรักษาจุดขยายดังกล่าวไว้ ภายใน คลาสนี้ทำหน้าที่เป็น facade โดยประกอบขึ้นจาก concern trait ที่มีความรับผิดชอบเดียว 25 รายการ และมอบหมายการดำเนินการ Portable Document Format (PDF) ทั้งหมดให้กับอินสแตนซ์ Document ที่สร้างขึ้นเมื่อสร้าง facade

ลำดับการบูต

Diagram

การสร้างอ็อบเจกต์เป็นขั้นตอน “boot” เพียงขั้นเดียว ตัวแพ็กเกจเองไม่ลงทะเบียน service container และไม่ทำการ bootstrap เฟรมเวิร์กใดๆ คุณเพิ่มการผสานรวมกับเฟรมเวิร์กเป็นเลเยอร์บางๆ ได้ ดู /integrations/tcpdf-compat/integration/

LegacyDefaults::register() เป็น idempotent โดยจะนิยามค่าคงที่ก็ต่อเมื่อค่าคงที่นั้นยังไม่ได้ถูกนิยามไว้ ค่าคงที่ที่แอปพลิเคชันกำหนดจะมีผลเหนือกว่าเสมอ หากคุณนิยามค่าเหล่านั้นก่อนการสร้างอ็อบเจกต์ครั้งแรก ดู /integrations/tcpdf-compat/configuration/ § Configuration resolution order

alias ของคลาสระดับ global แบบเลือกใช้

หากโค้ดเบสของคุณเรียก new \TCPDF(...) ใน global namespace และคุณยังเปลี่ยนจุดเรียกเหล่านั้นไม่ได้ ให้ลงทะเบียน alias ระดับ global เพียงครั้งเดียวระหว่างการบูตแอปพลิเคชัน:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() ลงทะเบียน \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS และ \TCPDF_IMAGES tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php ยืนยันพฤติกรรมนี้:

เป็น idempotent: การเรียกสองครั้งจะไม่ throw และจะลงทะเบียนเพียงครั้งเดียว
LegacyBootstrap::isRegistered() รายงานว่าถูกเรียกใช้งานแล้วหรือยัง
หลังจากลงทะเบียนแล้ว new \TCPDF() จะสร้างอินสแตนซ์ของอะแดปเตอร์

การหลีกเลี่ยงความขัดแย้งกับการติดตั้ง TCPDF จริง

นี่คือกฎที่สำคัญที่สุดเพียงข้อเดียวในหน้านี้

enableAliases() จะลงทะเบียน alias ก็ต่อเมื่อไม่มีคลาสที่ใช้ชื่อนั้นอยู่แล้วเท่านั้น (class_exists($alias, autoload: false)) ดังนั้น:

หาก tecnickcom/tcpdf ถูกติดตั้งไว้และ \TCPDF ของมันถูกโหลดก่อน alias จะถูกข้ามไปอย่างเงียบๆ และโค้ดของคุณจะยังคงใช้ TCPDF แบบเดิม ไม่ใช่อะแดปเตอร์
การรันไลบรารีทั้งสองโดยเปิดใช้ alias ระดับ global ในกระบวนการเดียวกันนั้นไม่รองรับ และจะทำให้เกิดพฤติกรรมที่กำกวม

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

การ binding ใน container

แพ็กเกจนี้ไม่ได้มาพร้อมกับ binding สำหรับ container ของเฟรมเวิร์ก หากคุณ bind facade ไว้ใน container ให้ bind เป็น factory ที่คืนค่า NextPDF\Compat\Tcpdf\TCPDF อินสแตนซ์ใหม่สำหรับแต่ละเอกสาร สถานะของเอกสารเป็นของแต่ละอินสแตนซ์ และต้องไม่แชร์ระหว่างเอกสารที่ไม่เกี่ยวข้องกัน ดู /integrations/tcpdf-compat/production-usage/ § Concurrency ส่วน /integrations/tcpdf-compat/integration/ แสดงตัวอย่างการ binding ทั่วไป

ลำดับการ resolve การกำหนดค่า

ขณะสร้างอ็อบเจกต์ อะแดปเตอร์จะ resolve การกำหนดค่าตามลำดับนี้: อาร์กิวเมนต์ของ constructor มาก่อน จากนั้นเป็นค่าคงที่แบบเดิมที่แอปพลิเคชันกำหนดไว้แล้ว และตามด้วยค่าเริ่มต้น TCPDF 6.2.13 ของ LegacyDefaults สำหรับค่าคงที่ใดๆ ที่ยังไม่ได้ถูกนิยามไว้ สำหรับรายละเอียดทั้งหมดและอ็อบเจกต์ AdaptationConfig แบบสมัยใหม่ ดู /integrations/tcpdf-compat/configuration/

การวินิจฉัย

เพื่อยืนยันว่า facade ถูกเชื่อมโยงไว้และลิงก์ไปยังเอนจิน resolve ได้ ให้สร้างอะแดปเตอร์ สร้าง PDF หนึ่งหน้า และตรวจสอบคำนำหน้า %PDF เทสต์เอาต์พุตของแพ็กเกจยืนยันผลลัพธ์เดียวกัน การตรวจสอบที่รันได้อยู่ใน /integrations/tcpdf-compat/install/ § Verify the installation

เพื่อตรวจจับความขัดแย้งกับ TCPDF จริงก่อนเปิดใช้ alias ให้ตรวจสอบว่ามี \TCPDF ระดับ global อยู่แล้วหรือไม่ ณ จุดที่คุณจะเรียก enableAliases() หากมีอยู่ alias จะถูกข้ามไป แก้ไขความขัดแย้งด้วยการ import แบบชัดเจน หรือนำ TCPDF จริงออกก่อนที่คุณจะพึ่งพาอะแดปเตอร์

ขอบเขตการครอบคลุม API ของ TCPDF

เมทริกซ์ความครอบคลุมที่เป็นแหล่งอ้างอิงและผ่านการตรวจสอบด้วยเทสต์คือไฟล์ในรีโพ docs/TCPDF_COVERAGE.md บทสรุปสำหรับผู้อ่าน รวมถึงรายการเมธอดที่ละเว้นแบบเงียบๆ และเมธอดที่ยังไม่ได้ implement อยู่ที่ /integrations/tcpdf-compat/method-coverage/ แพ็กเกจนี้ไม่ได้อ้างว่าเป็น “drop-in replacement” หรือ “100% TCPDF compatible” แต่เป็นทางเลือกที่เข้ากันได้กับ TCPDF โดยมีขอบเขตความเข้ากันได้ที่ทราบและผ่านการทดสอบ พร้อมความแตกต่างด้านพฤติกรรมที่ระบุไว้ในเอกสาร

ดูเพิ่มเติม

docs/TCPDF_COVERAGE.md — แหล่งอ้างอิงหลักด้านความครอบคลุม (ในรีโพ)
/integrations/tcpdf-compat/integration/ — การเชื่อมโยง facade เข้ากับ application/framework
/integrations/tcpdf-compat/method-coverage/ — พฤติกรรมและช่องว่างรายเมธอด
/integrations/tcpdf-compat/migration/ — กลยุทธ์การย้ายข้อมูลแบบเป็นขั้นตอน
/integrations/tcpdf-compat/troubleshooting/ — การวินิจฉัยความขัดแย้งระหว่าง alias/real-TCPDF
tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — oracle สำหรับพฤติกรรมของ alias