การผสานการทำงานของ compat-legacy สำหรับ NextPDF

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

ใช้ nextpdf/compat-legacy เพื่อเชื่อมต่อแอปพลิเคชันเข้ากับเอนจิน NextPDF เพื่อให้โค้ด TCPDF 6.x เดิมทำงานได้ แพ็กเกจนี้เป็น ตัวช่วยในการย้ายระบบ ไม่ใช่ shim ถาวร โดยให้นำออกหลังจากเปลี่ยนมาใช้ application programming interface (API) สมัยใหม่แล้ว (ดู /integrations/tcpdf-compat/migration/) แพ็กเกจนี้เป็นทางเลือกที่เข้ากันได้กับ TCPDF ไม่ใช่โคลนแบบ drop-in: จากเมท็อด TCPDF ที่สำรวจไว้ประมาณ 120 ตัว มี 94 ตัวที่ส่งต่อการทำงานโดยตรง เมท็อดที่เหลือมีความแตกต่างด้านพฤติกรรมที่บันทึกไว้แล้ว (ดู /integrations/tcpdf-compat/method-coverage/)

การติดตั้ง

composer require nextpdf/compat-legacy:^3.0

คำสั่งนี้จะ resolve nextpdf/core ^3.0 แบบ transitively สำหรับข้อกำหนดทั้งหมดและวิธีตรวจสอบยืนยัน โปรดดู /integrations/tcpdf-compat/install/

การบูตและการค้นพบอัตโนมัติ

แพ็กเกจนี้จะไม่ผูก globals ระหว่าง autoload และการ require แพ็กเกจนี้จะไม่สร้าง \TCPDF แบบ global ให้เลือกเองว่าจุดเรียกใช้จะ resolve คลาสอย่างไร:

แนวทางที่แนะนำ (การ import แบบชัดเจน) ปรับบรรทัด use/require ให้เป็น use NextPDF\Compat\Tcpdf\TCPDF; ในแต่ละไฟล์ วิธีนี้ชัดเจน ไม่กำกวม และค้นหาได้ง่าย
alias แบบ global ที่ต้องเลือกเปิดใช้ เรียก LegacyBootstrap::enableAliases() หนึ่งครั้งตอนบูตเพื่อลงทะเบียน \TCPDF และคลาสตัวช่วยทั้งสี่ เฉพาะกรณีที่ชื่อเหล่านั้นยังไม่ถูกใช้งานอยู่ก่อนแล้ว รายละเอียดกลไก ความเป็น idempotent และกฎการขัดแย้งกับ TCPDF ตัวจริง: /integrations/tcpdf-compat/boot-and-discovery/

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

// One call at application bootstrap, before any \TCPDF use.
LegacyBootstrap::enableAliases();

การ binding ใน container

แพ็กเกจนี้ไม่มี service provider หรือ bundle ของเฟรมเวิร์กติดมาด้วย เลเยอร์การผสานการทำงานแบบบางนี้จึงเป็นความรับผิดชอบของแอปพลิเคชัน ให้ bind factory ที่คืนค่า adapter ใหม่สำหรับเอกสารแต่ละชุด อย่าใช้ singleton ร่วมกันโดยเด็ดขาด เพราะแต่ละ instance ถือสถานะของเอกสารของตนเอง (ดู /integrations/tcpdf-compat/production-usage/ § Concurrency)

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use Psr\Container\ContainerInterface;

// Pseudocode for a PSR-11-style container: bind a factory, not a shared instance.
$container->set(TCPDF::class, static function (ContainerInterface $c): TCPDF {
    return new TCPDF('P', 'mm', 'A4');
});

// Each resolution is an independent document context.
$pdf = $container->get(TCPDF::class);

ใน Symfony ให้ลงทะเบียน factory เป็นบริการแบบ non-shared ใน Laravel ให้ใช้ bind (ไม่ใช่ singleton) เพื่อให้ทุกครั้งที่ resolve ได้ instance ใหม่ ตัวแพ็กเกจเองยังคงเป็นกลางต่อเฟรมเวิร์ก

การ publish การกำหนดค่า

ไม่มีไฟล์กำหนดค่าของเฟรมเวิร์กให้ publish กำหนดค่า adapter ผ่านค่าคงที่ K_* / PDF_* แบบเดิม (กำหนดค่าเหล่านี้ใน bootstrap ก่อนสร้าง instance ครั้งแรก) หรือผ่านอ็อบเจกต์ NextPDF\Compat\Tcpdf\Config\AdaptationConfig แบบ immutable สมัยใหม่ ดู /integrations/tcpdf-compat/configuration/

smoke test สำหรับ service provider / bundle

หลังจากเชื่อมต่อแล้ว ให้ตรวจสอบยืนยันว่าการผสานการทำงานสร้างไฟล์ Portable Document Format (PDF) ที่ถูกต้อง โค้ดนี้สะท้อนพื้นผิวการทำงานที่ tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php ยืนยันไว้:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Integration smoke test');

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

assert(str_starts_with($bytes, '%PDF'), 'Integration smoke test failed');
echo "Integration OK\n";

ในบริบทของ Hypertext Transfer Protocol (HTTP) หรือ worker ให้ใช้ Output(..., 'F') หรือ 'S' อย่าพึ่งพาเส้นทางแบบ inline สำหรับคำแนะนำการใช้งานทั้งหมด ดู /integrations/tcpdf-compat/production-usage/

จุดเข้าใช้งานของ public API

จุดเข้าใช้งาน	วัตถุประสงค์
`NextPDF\Compat\Tcpdf\TCPDF`	facade ที่เข้ากันได้กับ TCPDF สร้างหนึ่ง instance ต่อหนึ่งเอกสาร
`TCPDF::getDocument()`	คืนค่า `NextPDF\Core\Document` ที่ห่อหุ้มไว้ ซึ่งเป็นช่องทางลัดสู่ API สมัยใหม่
`TCPDF::setStrictMode(bool)`	สวิตช์เปิด/ปิดการตรวจสอบการย้ายระบบ (ดู /integrations/tcpdf-compat/configuration/)
`NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()`	alias คลาสแบบ global ที่ต้องเลือกเปิดใช้
`NextPDF\Compat\Tcpdf\Config\AdaptationConfig`	อ็อบเจกต์การกำหนดค่าแบบ immutable สมัยใหม่
`NextPDF\Compat\Contracts\CompatAdapterInterface`	contract สำหรับความเข้ากันได้ที่ใช้ร่วมกัน

ความครอบคลุมของ API TCPDF

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

ดูเพิ่มเติม

docs/TCPDF_COVERAGE.md — แหล่งข้อมูลอ้างอิงหลักด้านความครอบคลุมใน repo
/integrations/tcpdf-compat/boot-and-discovery/ — การเปิดเผย facade และพฤติกรรมของ alias
/integrations/tcpdf-compat/method-coverage/ — พฤติกรรมและช่องว่างรายเมท็อด
/integrations/tcpdf-compat/migration/ — กลยุทธ์การย้ายระบบแบบเป็นขั้นตอน
/integrations/tcpdf-compat/production-usage/ — วิธีรัน adapter ภายใต้ภาระงานหนัก
tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — oracle สำหรับพฤติกรรมเอาต์พุต