เริ่มต้นใช้งาน compat-legacy แบบรวดเร็ว

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

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

ก่อนเริ่มต้น

ติดตั้งแพ็กเกจและยืนยันการเชื่อมโยงกับเอนจินตามขั้นตอนใน /integrations/tcpdf-compat/install/ คุณต้องใช้ PHP 8.4 และต้องแก้ dependency ของ nextpdf/core ^3.0 ให้เรียบร้อย

1. สร้างเอกสารแรกของคุณ

เปลี่ยน import และคงการเรียกใช้แบบ TCPDF เดิมไว้ นี่คืออินเทอร์เฟซจริงที่ 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->SetCreator('Quickstart');
$pdf->SetTitle('First Document');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

เรียกใช้งาน:

php examples/quickstart-first.php

ไฟล์ quickstart.pdf เป็น PDF 2.0 ที่ถูกต้อง ชุดทดสอบยืนยันว่าสตริงเอาต์พุตที่เกี่ยวข้องขึ้นต้นด้วย %PDF สำหรับปลายทาง S, F และ E รวมถึงสำหรับ getPDFData()

ปลายทางของเอาต์พุต

Output($name, $dest) แมปโค้ดปลายทางของ TCPDF ผ่านบริดจ์เอาต์พุตที่ปลอดภัย ชุดทดสอบตรวจสอบพฤติกรรมนี้:

`$dest`	พฤติกรรม	ค่าที่ส่งคืน
`'S'`	ส่งคืน PDF เป็นสตริง	ไบต์ของ PDF (`%PDF…`)
`'F'`	เขียน PDF ไปยังพาธที่กำหนด	สตริงว่าง
`'E'`	ส่งคืน MIME body แบบ base64	บล็อก `Content-Type: application/pdf` จำนวนหนึ่งรายการ
`'I'`	แบบ inline (ค่าเริ่มต้น)	ตามบริดจ์เอาต์พุต
`'D'`	ดาวน์โหลด	ตามบริดจ์เอาต์พุต

ไม่เหมือน TCPDF เวอร์ชันเดิม Output() จะไม่ echo ลงในบัฟเฟอร์เอาต์พุตที่กำลังทำงานอยู่โดยตรง คุณจึงเรียกใช้ได้อย่างปลอดภัยภายใน queue worker หรือ HTTP handler ที่ควบคุมการตอบสนองของตนเอง ดู /integrations/tcpdf-compat/production-usage/

2. เรียกใช้โค้ด TCPDF ที่มีอยู่โดยไม่ต้องแก้ไข

สำหรับการย้ายระบบจริง ให้เริ่มจากการเรียกใช้โค้ดที่มีอยู่โดยเปลี่ยนเฉพาะ import หรือ alias เท่านั้น หากโค้ดเบสของคุณเรียกใช้ new \TCPDF(...) กับ global namespace ให้เปิดใช้งาน alias แบบ opt-in หนึ่งครั้งตอน boot (อธิบายไว้ใน /integrations/tcpdf-compat/boot-and-discovery/):

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

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

LegacyBootstrap::enableAliases() เป็น idempotent โดยจะลงทะเบียน \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS และ \TCPDF_IMAGES เฉพาะเมื่อคลาสเหล่านั้นยังไม่มีอยู่เท่านั้น การทดสอบของแพ็กเกจ tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php ยืนยันว่า alias ลงทะเบียนสำเร็จ การเรียกใช้เป็น idempotent และ new \TCPDF() เป็นอินสแตนซ์ของอะแดปเตอร์ อย่าเปิดใช้งาน alias หากไลบรารี TCPDF จริงถูกโหลดอยู่ในโปรเซสเดียวกัน ดู /integrations/tcpdf-compat/troubleshooting/

3. ตรวจสอบด้วยโหมดเข้มงวด

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

<?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 {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

การทดสอบของแพ็กเกจ tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php ยืนยันว่าการเรียกใช้แบบนี้ทุกประการจะโยนข้อยกเว้นในโหมดเข้มงวดและยังคงเงียบในโหมดเริ่มต้น และข้อความจะมีชื่อเมธอดกับพารามิเตอร์ที่ถูกละเว้น ใช้ข้อยกเว้นที่รวบรวมได้เป็นรายการงานสำหรับการย้ายระบบของคุณ ดู /integrations/tcpdf-compat/migration/

4. เข้าถึง API สมัยใหม่เมื่อคุณต้องการ

อินสแตนซ์ของอะแดปเตอร์ทุกตัวจะเปิดเผยเอกสารของเอนจินที่อยู่เบื้องหลัง ใช้เอกสารนี้เพื่อเรียกใช้เมธอด NextPDF สมัยใหม่ที่ไม่มีเมธอดเทียบเท่าใน TCPDF:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument() ส่งคืน NextPDF\Core\Document ที่อะแดปเตอร์ห่อหุ้มไว้ นี่คือเส้นทางออกที่แนะนำ: ย้ายจุดเรียกใช้ของคุณไปยัง API สมัยใหม่ทีละจุด จนกว่าคุณจะสามารถนำอะแดปเตอร์ออกได้

ความแตกต่างของพฤติกรรมที่ควรคาดการณ์ไว้ทันที

MultiCell() ส่งคืน 1 ไม่ใช่จำนวนเซลล์ที่เรนเดอร์ โค้ดที่แยกเส้นทางตามค่าที่ส่งคืนของ MultiCell() จำเป็นต้องปรับแก้
Error() จะโยน RuntimeException แทนการเรียก die() โค้ดที่เคยพึ่งพาการสิ้นสุดของโปรเซสจะต้องดักจับข้อยกเว้นนี้
ไบต์ของ PDF ที่แน่นอนแตกต่างจากเอาต์พุตของ TCPDF ปรับ baseline ใหม่สำหรับ assertion การทดสอบระดับไบต์ เพื่อให้ตรวจสอบเนื้อหาที่เรนเดอร์แทน

รายการแบบเต็มแยกตามเมธอดอยู่ใน /integrations/tcpdf-compat/method-coverage/

ขั้นตอนถัดไป

/integrations/tcpdf-compat/migration/ — กลยุทธ์การย้ายระบบแบบเต็มทีละไฟล์
/integrations/tcpdf-compat/configuration/ — โหมดเข้มงวด ค่าเริ่มต้น และอ็อบเจกต์การกำหนดค่าสมัยใหม่
/integrations/tcpdf-compat/production-usage/ — worker บัฟเฟอร์เอาต์พุต และประสิทธิภาพ
/integrations/tcpdf-compat/security-and-operations/ — แนวทางด้านการเข้ารหัสลับและการลงนาม

ดูเพิ่มเติม

tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — oracle ของพฤติกรรมเอาต์พุต
tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — oracle ของโหมดเข้มงวด
docs/TCPDF_COVERAGE.md — เมทริกซ์ความครอบคลุมที่เป็นแหล่งอ้างอิงอย่างเป็นทางการ