Bỏ qua để đến nội dung
NextPDF

Cấu hình compat-legacy

Tổng quan nhanh

Phần tiêu đề “Tổng quan nhanh”

Adapter cung cấp ba điểm cấu hình:

  1. Chế độ nghiêm ngặt — một công tắc dùng khi rà soát, biến các tham số bị âm thầm bỏ qua thành ngoại lệ. Theo mặc định, công tắc này tắt.
  2. Hằng số cũ — các hằng số TCPDF K_* / PDF_*, tự động được định nghĩa bằng các giá trị mặc định 6.2.13 để mã cũ đọc những hằng số này vẫn tiếp tục hoạt động.
  3. AdaptationConfig — một đối tượng cấu hình hiện đại, bất biến, thay thế cấu hình dựa trên hằng số.

Bạn vẫn cấu hình hầu hết các thiết lập tài liệu thông qua những phương thức TCPDF vốn đã gọi (SetMargins(), SetFont(), v.v.). Các phần dưới đây chỉ đề cập đến những điểm đặc thù của lớp tương thích.

Chế độ nghiêm ngặt

Phần tiêu đề “Chế độ nghiêm ngặt”

Chế độ nghiêm ngặt là thiết lập then chốt trong quá trình di chuyển. Chế độ này không thay đổi kết quả kết xuất. Nó quyết định liệu một lệnh gọi không thể tái tạo hành vi TCPDF sẽ báo lỗi rõ ràng hay âm thầm suy giảm.

examples/config-strict.php
<?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

Các kết quả này được xác nhận trong tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php:

Chế độGọi phương thức âm thầm bỏ qua tham sốKết quả
Tắt (mặc định)Ví dụ Image() với các tham số bổ sungChạy; các tham số bị bỏ qua không tạo tác dụng
Bậtcùng lệnh gọi đóNém TcpdfNotImplementedException và nêu tên các tham số bị bỏ qua
Bậtmột phương thức âm thầm bỏ qua tham số được gọi chỉ với các tham số được hỗ trợSẽ không ném ngoại lệ (e.g. SetProtection([], 'u', 'o', 0, []))

Chế độ nghiêm ngặt chỉ bổ sung thêm hành vi kiểm tra. Khi một phương thức hỗ trợ một tham số, adapter vẫn ủy thác lệnh gọi; chế độ nghiêm ngặt chỉ thêm lớp bảo vệ bằng ngoại lệ cho các tham số bị bỏ qua. Hãy dùng chế độ này trong một tác vụ tích hợp liên tục (CI) riêng hoặc trong một lượt kiểm tra chạy một lần, không dùng trong môi trường sản xuất. Điều này tuân theo nguyên tắc báo lỗi tường minh từ phần xử lý lỗi của Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) 5.0 (điều khoản reference_id được ghi trong sidecar RAG): bên gọi phải có khả năng nhận biết khi ý định của mình không được thực hiện.

Đừng triển khai mã sản xuất ra môi trường thực khi chế độ nghiêm ngặt đang bật. Một tham số bị âm thầm bỏ qua là vấn đề về trải nghiệm của lập trình viên, không phải lỗi lúc chạy, và một ngoại lệ trên đường dẫn kết xuất sản xuất còn tệ hơn kết quả bị suy giảm. Hãy kiểm tra, sửa, rồi tắt chế độ này — xem /integrations/tcpdf-compat/migration/.

Hằng số TCPDF cũ

Phần tiêu đề “Hằng số TCPDF cũ”

TCPDF cũ đọc cấu hình từ các hằng số K_* và PDF_*. Adapter tự động định nghĩa chúng khi khởi tạo chỉ khi chúng chưa được định nghĩa, dùng các giá trị mặc định của TCPDF 6.2.13. Nếu ứng dụng của bạn đã định nghĩa sẵn một hằng số (ví dụ, một K_PATH_FONTS tùy chỉnh), giá trị của bạn sẽ được giữ nguyên.

Một số giá trị mặc định tiêu biểu (danh sách đầy đủ: src/Compat/Tcpdf/Config/LegacyDefaults.php):

Hằng sốMặc địnhGhi chú
PDF_PAGE_FORMATA4
PDF_PAGE_ORIENTATIONP
PDF_UNITmm
PDF_MARGIN_LEFT / RIGHT15đơn vị người dùng
PDF_MARGIN_TOP27đơn vị người dùng
PDF_MARGIN_BOTTOM25đơn vị người dùng
PDF_FONT_NAME_MAINhelvetica
PDF_FONT_SIZE_MAIN10
K_CELL_HEIGHT_RATIO1.25
K_TCPDF_CALLS_IN_HTMLfalseđã được tăng cường bảo mật — luôn là false; markup không thể kích hoạt thực thi PHP
K_TCPDF_THROW_EXCEPTION_ERRORtrueđã được tăng cường bảo mật — Error() luôn ném ngoại lệ; không bao giờ gọi die()
K_TIMEZONEUTC

Hai giá trị trong số này được cố ý cố định vì lý do an toàn và không thể nới lỏng bằng cấu hình: K_TCPDF_CALLS_IN_HTML luôn là false, và K_TCPDF_THROW_EXCEPTION_ERROR trên thực tế luôn là true. Nếu mã cũ phụ thuộc vào một trong hai hành vi cũ không an toàn này, bạn phải thay đổi mã đó — xem /integrations/tcpdf-compat/security-and-operations/.

Hãy định nghĩa các hằng số tùy chỉnh trước lần khởi tạo adapter đầu tiên, thường là trong phần bootstrap của ứng dụng:

examples/config-constants.php
<?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.

Đối tượng AdaptationConfig hiện đại

Phần tiêu đề “Đối tượng AdaptationConfig hiện đại”

Nếu bạn không muốn dựa vào các hằng số toàn cục, hãy dùng đối tượng giá trị cấu hình bất biến, NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Đối tượng này là final readonly, và mọi trường đều mặc định theo giá trị của TCPDF 6.2.13. Bạn có thể khởi tạo nó chỉ với những trường muốn thay đổi.

Bạn cũng có thể tạo đối tượng này từ bất kỳ hằng số cũ nào hiện đã được định nghĩa:

examples/config-adaptation.php
<?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 là đích đến của quá trình di chuyển cấu hình. Khi chuyển các điểm gọi sang API hiện đại, hãy thay thế việc tra cứu hằng số bằng các trường AdaptationConfig tường minh. Nhờ đó, cấu hình giữ được kiểu dữ liệu và nằm trong phạm vi cục bộ thay vì toàn cục.

Thứ tự phân giải cấu hình

Phần tiêu đề “Thứ tự phân giải cấu hình”

Khi khởi tạo một tài liệu, adapter phân giải cấu hình theo thứ tự này. Các bước sau không ghi đè bước trước:

  1. Các đối số của hàm khởi tạo (orientation, unit, format, …) — có độ ưu tiên cao nhất đối với những giá trị mà chúng bao quát.
  2. Các hằng số cũ đã có sẵn do ứng dụng định nghĩa.
  3. Các hằng số mặc định của TCPDF 6.2.13, được LegacyDefaults tự động định nghĩa cho bất kỳ hằng số nào chưa được định nghĩa.

Các đối số của hàm khởi tạo unicode, encoding và diskcache được chấp nhận để giữ tương thích chữ ký và không có tác dụng. NextPDF luôn dùng Unicode và UTF-8, đồng thời không dùng bộ nhớ đệm trang trên đĩa. Cờ khởi tạo pdfa cũng được chấp nhận, nhưng tuân thủ lưu trữ PDF/A đòi hỏi một phiên bản thương mại (xem /integrations/tcpdf-compat/security-and-operations/).

Xem thêm

Phần tiêu đề “Xem thêm”
  • src/Compat/Tcpdf/Config/LegacyDefaults.php — nguồn chính thức cho các giá trị mặc định của hằng số
  • src/Compat/Tcpdf/Config/AdaptationConfig.php — đối tượng cấu hình hiện đại
  • /integrations/tcpdf-compat/migration/ — chuyển cấu hình ra khỏi các hằng số toàn cục
  • /integrations/tcpdf-compat/security-and-operations/ — hai cờ đã được tăng cường bảo mật, không thể cấu hình