Konfiguracja compat-legacy

W skrócie

Adapter udostępnia trzy obszary konfiguracji:

Tryb ścisły — przełącznik audytu, który zamienia cichą utratę parametrów w wyjątki. Domyślnie jest wyłączony.
Starsze stałe — stałe K_* / PDF_* z TCPDF, definiowane automatycznie z domyślnymi wartościami z wersji 6.2.13, dzięki czemu starszy kod, który je odczytuje, nadal działa.
AdaptationConfig — nowoczesny, niezmienny obiekt konfiguracji, który zastępuje konfigurację opartą na stałych.

Większość ustawień dokumentu nadal ustawiasz metodami TCPDF, które już wywołujesz (SetMargins(), SetFont() i tak dalej). Poniższe sekcje opisują tylko to, co jest specyficzne dla warstwy zgodności.

Tryb ścisły

Tryb ścisły to kluczowe ustawienie podczas migracji. Nie zmienia renderowanego wyniku. Decyduje o tym, czy wywołanie, które nie może odtworzyć zachowania TCPDF, kończy się jawnym błędem, czy degraduje się po cichu.

<?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

Takie wyniki weryfikuje tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php:

Tryb	Wywołanie metody, która cicho ignoruje parametry	Wynik
Wyłączony (domyślnie)	np. `Image()` z dodatkowymi parametrami	Wykonuje się; ignorowane parametry nie mają wpływu
Włączony	to samo wywołanie	Zgłasza `TcpdfNotImplementedException` z nazwami zignorowanych parametrów
Włączony	metoda, która cicho ignoruje parametry, wywołana wyłącznie z obsługiwanymi parametrami	Nie zgłasza wyjątku (np. `SetProtection([], 'u', 'o', 0, [])`)

Tryb ścisły ma charakter addytywny. Gdy metoda obsługuje dany parametr, wywołanie nadal jest delegowane; tryb ścisły dodaje zabezpieczenie w postaci wyjątku tylko dla parametrów, które są pomijane. Używaj go w dedykowanym zadaniu ciągłej integracji (CI) albo w jednorazowym przebiegu audytu, a nie na produkcji. Jest to zgodne z zasadą jawnego sygnalizowania błędów w ramach obsługi błędów w Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) 5.0 (klauzula reference_id zapisana w pliku pomocniczym RAG): wywołujący musi mieć możliwość zauważenia, kiedy jego intencja nie została spełniona.

Nie wdrażaj na produkcję kodu z włączonym trybem ścisłym. Po cichu zignorowany parametr to problem z ergonomią pracy programisty, a nie błąd środowiska wykonawczego, a wyjątek na produkcyjnej ścieżce renderowania jest gorszy niż zdegradowany wynik. Przeprowadź audyt, popraw problemy, a następnie go wyłącz — zobacz /integrations/tcpdf-compat/migration/.

Starsze stałe TCPDF

Starszy kod TCPDF odczytuje konfigurację ze stałych K_* i PDF_*. Adapter definiuje je automatycznie podczas konstruowania tylko wtedy, gdy nie zostały wcześniej zdefiniowane, używając domyślnych wartości z TCPDF 6.2.13. Jeśli aplikacja już definiuje daną stałą (na przykład własną K_PATH_FONTS), jej wartość zostaje zachowana.

Wybrane wartości domyślne (pełna lista: src/Compat/Tcpdf/Config/LegacyDefaults.php):

Stała	Wartość domyślna	Uwaga
`PDF_PAGE_FORMAT`	`A4`
`PDF_PAGE_ORIENTATION`	`P`
`PDF_UNIT`	`mm`
`PDF_MARGIN_LEFT` / `RIGHT`	`15`	jednostki użytkownika
`PDF_MARGIN_TOP`	`27`	jednostki użytkownika
`PDF_MARGIN_BOTTOM`	`25`	jednostki użytkownika
`PDF_FONT_NAME_MAIN`	`helvetica`
`PDF_FONT_SIZE_MAIN`	`10`
`K_CELL_HEIGHT_RATIO`	`1.25`
`K_TCPDF_CALLS_IN_HTML`	`false`	wzmocnione — zawsze false; znaczniki nie mogą spowodować wykonania kodu PHP
`K_TCPDF_THROW_EXCEPTION_ERROR`	`true`	wzmocnione — `Error()` zawsze zgłasza wyjątek; nigdy `die()`
`K_TIMEZONE`	`UTC`

Dwie z nich ze względów bezpieczeństwa celowo mają stałą wartość i nie można ich osłabić przez konfigurację: K_TCPDF_CALLS_IN_HTML jest zawsze false, a K_TCPDF_THROW_EXCEPTION_ERROR jest w praktyce zawsze true. Jeśli starszy kod zależy od któregokolwiek z tych dawnych, niebezpiecznych zachowań, musi zostać zmieniony — zobacz /integrations/tcpdf-compat/security-and-operations/.

Zdefiniuj własne stałe przed pierwszym skonstruowaniem adaptera, najczęściej w pliku startowym aplikacji:

<?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.

Nowoczesny obiekt AdaptationConfig

Jeśli nie chcesz polegać na stałych globalnych, użyj niezmiennego obiektu wartości konfiguracji NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Jest final readonly, a każde pole domyślnie przyjmuje wartość z TCPDF 6.2.13. Możesz go utworzyć, podając tylko te pola, które chcesz zmienić.

Możesz też zbudować go na podstawie tych starszych stałych, które są obecnie zdefiniowane:

<?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 jest docelowym sposobem migracji konfiguracji. W miarę przenoszenia miejsc wywołań na nowoczesny interfejs API zastępuj odczyty stałych jawnymi polami AdaptationConfig. Konfiguracja pozostaje typowana i lokalna, a nie globalna.

Kolejność rozstrzygania konfiguracji

Gdy adapter konstruuje dokument, rozstrzyga konfigurację w następującej kolejności. Późniejsze kroki nie nadpisują wcześniejszych:

Argumenty konstruktora (orientation, unit, format, …) — najwyższy priorytet dla wartości, których dotyczą.
Wcześniej zdefiniowane przez aplikację starsze stałe.
Domyślne stałe z TCPDF 6.2.13, definiowane automatycznie przez LegacyDefaults dla każdej stałej, która nie jest jeszcze zdefiniowana.

Argumenty konstruktora unicode, encoding i diskcache są akceptowane dla zgodności sygnatury i nie mają wpływu. NextPDF zawsze używa Unicode i UTF-8 oraz nie używa dyskowej pamięci podręcznej stron. Flaga konstruktora pdfa jest również akceptowana, ale archiwalna zgodność z PDF/A wymaga edycji komercyjnej (zobacz /integrations/tcpdf-compat/security-and-operations/).

Zobacz także

src/Compat/Tcpdf/Config/LegacyDefaults.php — autorytatywne wartości domyślne stałych
src/Compat/Tcpdf/Config/AdaptationConfig.php — nowoczesny obiekt konfiguracji
/integrations/tcpdf-compat/migration/ — przenoszenie konfiguracji ze stałych globalnych
/integrations/tcpdf-compat/security-and-operations/ — dwie wzmocnione, niekonfigurowalne flagi