การกำหนดค่า compat-legacy

ภาพรวมโดยสังเขป

อะแดปเตอร์มีอินเทอร์เฟซการกำหนดค่าสามแบบ:

Strict mode — สวิตช์การตรวจสอบที่เปลี่ยนการละทิ้งพารามิเตอร์อย่างเงียบๆให้เป็นข้อยกเว้น และปิดไว้ตามค่าเริ่มต้น
Legacy constants — ค่าคงที่ TCPDF K_* / PDF_* ที่ถูกกำหนดโดยอัตโนมัติด้วยค่าเริ่มต้นของ TCPDF 6.2.13 เพื่อให้โค้ดแบบเดิมที่อ่านค่าเหล่านี้ยังทำงานได้
AdaptationConfig — ออบเจ็กต์การกำหนดค่าสมัยใหม่ที่เปลี่ยนแปลงไม่ได้ ซึ่งใช้แทนการกำหนดค่าผ่านค่าคงที่

ยังคงกำหนดค่าการตั้งค่าเอกสารส่วนใหญ่ผ่านเมธอด TCPDF ที่ใช้งานอยู่แล้ว (SetMargins(), SetFont() และอื่นๆ) ส่วนต่างๆด้านล่างนี้ครอบคลุมเฉพาะส่วนที่เป็นลักษณะเฉพาะของเลเยอร์ความเข้ากันได้เท่านั้น

โหมดเข้มงวด (Strict mode)

Strict mode คือการตั้งค่าหลักสำหรับงานย้ายระบบ โหมดนี้ไม่เปลี่ยนผลลัพธ์ที่เรนเดอร์ แต่ใช้ควบคุมว่าการเรียกที่ไม่สามารถจำลองพฤติกรรมของ TCPDF ได้จะล้มเหลวอย่างชัดเจนหรือลดทอนคุณภาพอย่างเงียบๆ

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();

$pdf->setStrictMode(true);   // audit: throw on silent parameter loss
$isOn = $pdf->isStrictMode(); // true
$pdf->setStrictMode(false);  // back to backward-compatible default

ผลลัพธ์เหล่านี้ได้รับการยืนยันโดย tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php:

โหมด	มีการเรียกเมธอดที่ละเลยพารามิเตอร์อย่างเงียบๆ	ผลลัพธ์
ปิด (ค่าเริ่มต้น)	e.g. `Image()` ที่มีพารามิเตอร์เพิ่มเติม	ทำงานได้; พารามิเตอร์ที่ถูกละเลยไม่มีผลใดๆ
เปิด	การเรียกแบบเดียวกัน	โยน `TcpdfNotImplementedException` โดยระบุชื่อพารามิเตอร์ที่ถูกละเลย
เปิด	เมธอดที่มีพฤติกรรมละเลยพารามิเตอร์อย่างเงียบๆ แต่ถูกเรียกด้วยพารามิเตอร์ที่รองรับเท่านั้น	จะไม่โยนข้อยกเว้น (e.g. `SetProtection([], 'u', 'o', 0, [])`)

Strict mode เป็นการตรวจสอบเพิ่มเติมอีกชั้นหนึ่ง เมื่อเมธอดรองรับพารามิเตอร์ เมธอดจะยังส่งต่อการทำงานตามเดิม; strict mode เพียงเพิ่มการป้องกันด้วยข้อยกเว้นสำหรับพารามิเตอร์ที่ถูกทิ้งไปเท่านั้น ใช้โหมดนี้ในงาน continuous integration (CI) ที่แยกไว้เฉพาะหรือการตรวจสอบแบบครั้งเดียว ไม่ใช่ในระบบที่ใช้งานจริง แนวทางนี้สอดคล้องกับหลักการล้มเหลวอย่างชัดเจนจากการจัดการข้อผิดพลาดของ Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) 5.0 (clause reference_id ที่บันทึกไว้ใน RAG sidecar): ผู้เรียกต้องรับรู้ได้เมื่อระบบไม่ได้ทำตามเจตนาที่ระบุไว้

อย่านำโค้ดไปใช้งานจริงโดยเปิด strict mode ไว้ พารามิเตอร์ที่ถูกละเลยอย่างเงียบๆ เป็นปัญหาด้านประสบการณ์ของนักพัฒนา ไม่ใช่ข้อผิดพลาดในขณะรันไทม์ และ ข้อยกเว้นในเส้นทางการเรนเดอร์ของระบบที่ใช้งานจริงสร้างผลเสียมากกว่าการได้ผลลัพธ์ที่ถูกลดทอนคุณภาพ ตรวจสอบ แก้ไข แล้วจึงปิด — ดู /integrations/tcpdf-compat/migration/

ค่าคงที่ TCPDF แบบเดิม

TCPDF แบบเดิมอ่านการกำหนดค่าจากค่าคงที่ K_* และ PDF_* อะแดปเตอร์จะกำหนดค่าคงที่เหล่านี้โดยอัตโนมัติเมื่อสร้างออบเจ็กต์ เฉพาะเมื่อยังไม่ได้ถูกกำหนดไว้ โดยใช้ค่าเริ่มต้นของ TCPDF 6.2.13 หากแอปพลิเคชันกำหนดค่าคงที่ไว้แล้ว (ตัวอย่างเช่น K_PATH_FONTS แบบกำหนดเอง) ค่านั้นจะถูกรักษาไว้

ค่าเริ่มต้นบางรายการที่คัดมา (รายการทั้งหมด: src/Compat/Tcpdf/Config/LegacyDefaults.php):

ค่าคงที่	ค่าเริ่มต้น	หมายเหตุ
`PDF_PAGE_FORMAT`	`A4`
`PDF_PAGE_ORIENTATION`	`P`
`PDF_UNIT`	`mm`
`PDF_MARGIN_LEFT` / `RIGHT`	`15`	หน่วยของผู้ใช้
`PDF_MARGIN_TOP`	`27`	หน่วยของผู้ใช้
`PDF_MARGIN_BOTTOM`	`25`	หน่วยของผู้ใช้
`PDF_FONT_NAME_MAIN`	`helvetica`
`PDF_FONT_SIZE_MAIN`	`10`
`K_CELL_HEIGHT_RATIO`	`1.25`
`K_TCPDF_CALLS_IN_HTML`	`false`	เสริมความปลอดภัย — เป็น false เสมอ; มาร์กอัปไม่สามารถเรียกให้ประมวลผล PHP ได้
`K_TCPDF_THROW_EXCEPTION_ERROR`	`true`	เสริมความปลอดภัย — `Error()` โยนข้อยกเว้นเสมอ; ไม่เคย `die()`
`K_TIMEZONE`	`UTC`

ค่าคงที่สองรายการนี้ถูกตรึงค่าไว้โดยเจตนาเพื่อความปลอดภัยและไม่สามารถทำให้ผ่อนปรนผ่านการกำหนดค่าได้: K_TCPDF_CALLS_IN_HTML เป็น false เสมอ และ K_TCPDF_THROW_EXCEPTION_ERROR มีผลเป็น true เสมอ หากโค้ดแบบเดิมพึ่งพาพฤติกรรมที่ไม่ปลอดภัยข้อใดข้อหนึ่ง ต้องปรับโค้ดนั้น — ดู /integrations/tcpdf-compat/security-and-operations/

ให้กำหนดค่าคงที่แบบกำหนดเองก่อนการสร้างอะแดปเตอร์ครั้งแรก โดยปกติจะอยู่ในขั้นตอน bootstrap ของแอปพลิเคชัน:

<?php

declare(strict_types=1);

// Define BEFORE constructing the adapter; the adapter will not override it.
define('PDF_CREATOR', 'My Application');
define('PDF_AUTHOR', 'My Application');

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
// Creator and Author are seeded from your constants.

ออบเจ็กต์ AdaptationConfig แบบสมัยใหม่

หากไม่ต้องการพึ่งพาค่าคงที่ส่วนกลาง ให้ใช้ออบเจ็กต์ค่าการกำหนดค่าที่เปลี่ยนแปลงไม่ได้ NextPDF\Compat\Tcpdf\Config\AdaptationConfig ออบเจ็กต์นี้เป็น final readonly และทุกฟิลด์มีค่าเริ่มต้นตาม TCPDF 6.2.13 สามารถสร้างออบเจ็กต์นี้ได้โดยระบุเฉพาะฟิลด์ที่ต้องการเปลี่ยนแปลงเท่านั้น

ยังสามารถสร้างออบเจ็กต์นี้จากค่าคงที่แบบเดิมที่มีการกำหนดไว้ ณ ขณะนั้นได้:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Config\AdaptationConfig;

// Snapshot the currently-defined legacy constants into an object:
$config = AdaptationConfig::fromLegacyConstants();

echo $config->pageFormat;   // 'A4' unless a constant overrides it
echo $config->fontNameMain; // 'helvetica'
echo $config->marginLeft;   // 15.0

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

ลำดับการใช้ค่ากำหนด

เมื่ออะแดปเตอร์สร้างเอกสาร ระบบจะเลือกใช้ค่ากำหนดตามลำดับต่อไปนี้ โดยขั้นตอนภายหลังจะไม่แทนที่ขั้นตอนก่อนหน้า:

อาร์กิวเมนต์ของคอนสตรักเตอร์ (orientation, unit, format, …) — มีลำดับความสำคัญสูงสุดสำหรับค่าที่อาร์กิวเมนต์เหล่านี้ครอบคลุม
ค่าคงที่แบบเดิมที่แอปพลิเคชันกำหนดไว้ก่อนแล้ว
ค่าเริ่มต้นของค่าคงที่ TCPDF 6.2.13 ซึ่งถูกกำหนดโดยอัตโนมัติด้วย LegacyDefaults สำหรับค่าคงที่ที่ยังไม่ได้ถูกกำหนดไว้

อาร์กิวเมนต์ของคอนสตรักเตอร์ unicode, encoding และ diskcache ได้รับการยอมรับเพื่อให้ลายเซ็นเข้ากันได้และไม่มีผลใดๆ NextPDF เป็น Unicode และ UTF-8 เสมอ และไม่มีแคชหน้าบนดิสก์ แฟล็กคอนสตรักเตอร์ pdfa ก็ได้รับการยอมรับเช่นกัน แต่ความสอดคล้องสำหรับการจัดเก็บถาวรแบบ PDF/A ต้องใช้รุ่นเชิงพาณิชย์ (ดู /integrations/tcpdf-compat/security-and-operations/)

ดูเพิ่มเติม

src/Compat/Tcpdf/Config/LegacyDefaults.php — แหล่งอ้างอิงหลักสำหรับค่าเริ่มต้นของค่าคงที่
src/Compat/Tcpdf/Config/AdaptationConfig.php — ออบเจ็กต์การกำหนดค่าแบบสมัยใหม่
/integrations/tcpdf-compat/migration/ — การย้ายการกำหนดค่าออกจากค่าคงที่ส่วนกลาง
/integrations/tcpdf-compat/security-and-operations/ — แฟล็กเสริมความปลอดภัยสองรายการที่กำหนดค่าไม่ได้