Pokrycie metod TCPDF w warstwie nextpdf/compat-legacy

W skrócie

nextpdf/compat-legacy to warstwa zgodności, a nie odgałęzienie TCPDF ani gwarantowany klon jego zachowania. Na bazie silnika rdzenia NextPDF udostępnia publiczne nazwy metod TCPDF 6.x, kolejność parametrów i wartości domyślne. Większość wywołań jest odwzorowywana bezpośrednio na operację NextPDF Document. Niewielka część przyjmuje starsze parametry, których NextPDF nie uwzględnia albo które nie mają żadnego efektu.

Ta strona przedstawia audyt poszczególnych metod. Autorytatywna, zweryfikowana testami macierz pokrycia znajduje się w repozytorium, w pliku docs/TCPDF_COVERAGE.md. W razie rozbieżności między tą stroną a macierzą w repozytorium rozstrzyga macierz, ponieważ to ją weryfikuje zestaw testów.

Skorzystaj z tej strony, aby przed migracją odpowiedzieć sobie na jedno pytanie: co adapter faktycznie robi z każdą metodą TCPDF wywoływaną w mojej bazie kodu?

Podsumowanie pokrycia

Audyt objął około 120 publicznych metod TCPDF 6.x. Każdą metodę przypisano do dokładnie jednej z czterech kategorii.

Kategoria	Liczba	Co to dla Ciebie oznacza
Odwzorowane — w pełni delegowane	94	Wywołanie jest odwzorowywane bezpośrednio na metodę NextPDF `Document`. Zachowanie jest zgodne dla udokumentowanych parametrów.
Ciche pomijanie — częściowe	15	Metoda działa i generuje dane wyjściowe, ale co najmniej jeden parametr TCPDF nie ma żadnego efektu. Jest to udokumentowana różnica w zachowaniu.
Niezaimplementowane — puste ciało metody	4	Metoda istnieje dla zgodności na poziomie kodu źródłowego, ale nic nie robi.
Nie dotyczy	7	Metoda TCPDF nie ma wpływu na wyjście PDF; celowo pominięta.
Dodane metody dryfu nowoczesnego API	17	Metody Document z NextPDF v5.1+ udostępnione w adapterze, aby kod łączący różne API nadal się kompilował. Nie mają one odpowiednika w TCPDF 6.x.

Liczby te pochodzą z docs/TCPDF_COVERAGE.md §Summary. Zestaw testów weryfikuje macierz za pomocą tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php oraz tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php.

Uwaga dotycząca sformułowania. Ten pakiet nie rości sobie miana „zamiennika bezpośredniego” ani „w 100% zgodnego z TCPDF”. Zapewnia bezpośrednią delegację dla 94 z badanych ~120 metod TCPDF. Pozostałe metody mają udokumentowane różnice w zachowaniu, opisane poniżej. Trafny opis to alternatywa zgodna z TCPDF o znanej, przetestowanej powierzchni zgodności.

Uwaga dotycząca liczby metod

Adapter zbudowano z 25 cech (traits) o jednej odpowiedzialności (src/Compat/Tcpdf/Concerns/), które łącznie udostępniają 273 metody publiczne, oraz z niewielkiej liczby metod cyklu życia i metod awaryjnych w samej klasie TCPDF. Powyższe kategorie pokrycia liczą odrębne metody powierzchni API TCPDF 6.x (~120), a nie łączną liczbę publicznych metod adaptera. Te dwie wartości mierzą różne rzeczy: pokrycie powierzchni API oraz rozmiar implementacji. Jeśli plik README.md pakietu podaje mniejszą liczbę cech lub metod, za autorytatywne uznawaj docs/TCPDF_COVERAGE.md oraz tę stronę. Podsumowanie w pliku README powstało przed wprowadzeniem cechy AdaptsDriftV51.

1. Metody odwzorowane — zgodna delegacja

Dziewięćdziesiąt cztery metody delegują bezpośrednio do bazowej instancji NextPDF\Core\Document. Nazwy TCPDF w notacji PascalCase są odwzorowywane na nazwy NextPDF w notacji camelCase tam, gdzie silnik stosuje camelCase. Adapter akceptuje obie pisownie ze względu na zgodność wsteczną i zgodność w przód.

Reprezentatywne grupy (pełna tabela: docs/TCPDF_COVERAGE.md §1):

Obszar TCPDF	Przykładowe metody	Cecha adaptera
Cykl życia	`Output()`, `Close()`, `getPDFData()`	`AdaptsLifecycle`
Strony	`AddPage()`, `getNumPages()`, `deletePage()`	`AdaptsPageManagement`
Tekst	`Cell()`, `MultiCell()`, `Write()`, `Text()`, `Ln()`	`AdaptsTextOutput`
Czcionki	`SetFont()`, `SetFontSize()`, `AddFont()`	`AdaptsFonts`
Kolory	`SetTextColor()`, `SetDrawColor()`, `SetFillColor()`	`AdaptsColors`
Rysowanie	`Line()`, `Rect()`, `Circle()`, `Polygon()`, `Arrow()`	`AdaptsDrawing`
Przekształcenia	`Rotate()`, `Scale()`, `Translate()`, `Skew()`, `Mirror*()`	`AdaptsTransforms`
Nawigacja	`AddLink()`, `Annotation()`, `addTOC()`	`AdaptsNavigation`

W przypadku tych metod obserwowane zachowanie jest zgodne z TCPDF 6.x w zakresie parametrów udokumentowanych przez NextPDF. Adapter nie gwarantuje wyjścia PDF identycznego bajtowo. Bazowy silnik to niezależna implementacja PDF 2.0, więc bajty mogą się różnić nawet wtedy, gdy widoczny rezultat jest równoważny. Jeśli Twoje testy sprawdzają dokładne bajty PDF zamiast wyrenderowanej treści, spodziewaj się konieczności ustalenia nowej wartości bazowej dla tych asercji. Zalecaną strategię ustalania nowej wartości bazowej opisuje /integrations/tcpdf-compat/migration/.

2. Metody cichego pomijania — udokumentowane różnice w zachowaniu

Te 15 metod działa i generuje dane wyjściowe, ale co najmniej jeden parametr TCPDF jest przyjmowany dla zgodności na poziomie kodu źródłowego, a następnie ignorowany. Przeczytaj tę sekcję przed migracją. Te wywołania nie kończą się błędem; po cichu wykonują mniej pracy niż oryginał z TCPDF.

Metoda TCPDF	Ignorowane parametry	Zgodna alternatywa
`Image()`	type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs	NextPDF `image()` przyjmuje file, x, y, width, height. Aby uzyskać klikalny obraz, narysuj obraz, a następnie dodaj `Document::link()` dla tego samego prostokąta. Maskowanie obrazów oraz obrazy alternatywne nie są obsługiwane.
`writeHTML()`	ln, fill, reseth, cell, align	NextPDF `writeHtml()` obsługuje wyłącznie treść. Aby kontrolować układ, opakuj HTML w blok pozycjonowany za pomocą nowoczesnego API.
`writeHTMLCell()`	border (w postaci łańcucha znaków), ln, fill, reseth, autopadding	Szerokość, wysokość, pozycja oraz logiczne obramowanie są uwzględniane; bogatszy układ komórki nie ma odwzorowania.
`ImageEps()`	link, useBoundingBox, align, palign, border, fitonpage, fixoutvals	Tylko pozycja i rozmiar.
`ImageSVG()`	link, align, palign, border, fitonpage	Tylko pozycja i rozmiar.
`SetProtection()`	mode (niezerowy), pubkeys (niepusty)	NextPDF zawsze stosuje AES-256 w standardowym mechanizmie obsługi. W przypadku szyfrowania opartego na certyfikatach użyj nowoczesnej metody `setPublicKeyEncryption()` udostępnionej w adapterze (zobacz /integrations/tcpdf-compat/security-and-operations/).
`Bookmark()`	style, color, x, isNamedDest	Tytuł, poziom oraz pozycja y są uwzględniane.
`setDestination()`	page, x	Nazwa oraz pozycja y są uwzględniane.
`Link()`	spaces	Wewnętrzne śledzenie białych znaków w TCPDF; brak odpowiednika w silniku.
`Annotation()`	klucze opcji inne niż Subtype, spaces	Typ, pozycja oraz tekst są uwzględniane.
`SetLineStyle()`	szczegóły wzoru kreskowania poza szerokością	Podstawowe właściwości linii są odwzorowane.
`setAlpha()`	częściowe odwzorowanie trybów mieszania	Niektóre nazwy trybów mieszania nie mają odpowiednika w silniku.
`Polycurve()`	pełna lista parametrów	Brak działania w trybie domyślnym; brak odpowiednika w silniku.
`PieSectorXY()`	pełna lista parametrów	Częściowe odwzorowanie (linie od środka do krawędzi różnią się).
`RoundedRectXY()`	promień osobny dla każdego narożnika	Tylko jednolity promień narożników.

To, jak adapter sygnalizuje te różnice, zależy od trybu ścisłego (zobacz /integrations/tcpdf-compat/configuration/). Gdy tryb ścisły jest wyłączony (ustawienie domyślne zachowujące zgodność wsteczną), te wywołania po cichu wykonują się w ograniczonym zakresie. Gdy tryb ścisły jest włączony, każde wywołanie ignorujące parametr zgłasza TcpdfNotImplementedException z dokładną listą ignorowanych parametrów oraz wskazówką migracyjną. Tryb ścisły służy do audytu, a nie jako ustawienie produkcyjne.

Projekt trybu ścisłego opiera się na zasadzie, że kod wywołujący musi mieć możliwość zauważenia, kiedy jego intencja nie została uwzględniona. OWASP ASVS 5.0 §16.5.3 stwierdza, że aplikacje powinny kończyć się niepowodzeniem w sposób kontrolowany i bezpieczny oraz zapobiegać sytuacjom typu fail-open. Ciche pominięcie parametru to raczej problem z doświadczeniem programisty niż podatność, ale obowiązuje ta sama zasada jawnego sygnalizowania błędów. Skrócone odniesienie do klauzuli znajduje się w sekcji citations we front-matterze strony.

3. Metody niezaimplementowane — puste ciała metod

Cztery metody istnieją po to, aby starszy kod źródłowy się kompilował, ale ich ciała nie wykonują żadnych działań. Przy włączonym trybie ścisłym trzy z nich zgłaszają TcpdfNotImplementedException. Czwarta (Open()) jest celową, bezpieczną metodą bez działania, która nigdy nie zgłasza wyjątku, ponieważ zawsze można ją bezpiecznie usunąć ze starszego kodu.

Metoda TCPDF	Zachowanie	Zamiennik
`setSignature()`	Brak działania (nie przechowuje niczego, co można byłoby wykorzystać). Zgłasza wyjątek w trybie ścisłym.	Podpisywanie cyfrowe wymaga komercyjnej edycji NextPDF. Użyj nowoczesnego API podpisu z obiektem wartości `CertificateInfo`; zobacz /integrations/tcpdf-compat/security-and-operations/.
`addEmptySignatureAppearance()`	Brak działania. Zgłasza wyjątek w trybie ścisłym.	Ta sama bramka edycji komercyjnej co dla `setSignature()`.
`endPage()`	Brak działania. Zgłasza wyjątek w trybie ścisłym.	NextPDF automatycznie zarządza cyklem życia stron. Usuń wywołanie.
`Open()`	Bezpieczny brak działania. Nigdy nie zgłasza wyjątku.	NextPDF automatycznie otwiera dokument. Usunięcie tego wywołania jest zawsze bezpieczne.

Podpisywanie nie jest dostępne w silniku rdzenia za pośrednictwem tego adaptera. Adapter udostępnia nowoczesny punkt wejścia do podpisu, który deleguje do silnika. Podstawowa obsługa podpisu jest ograniczona do edycji komercyjnej. Ta dokumentacja nie składa żadnych deklaracji dotyczących profili weryfikacji długoterminowej ani podpisów ze znacznikiem czasu dla żadnej edycji. Dokładne, ostrożne sformułowanie zawiera /integrations/tcpdf-compat/security-and-operations/.

4. Metody niemające zastosowania

Siedem metod TCPDF nie ma wpływu na dane wyjściowe PDF i zostało celowo pominiętych. Można je bezpiecznie wywoływać.

Metoda TCPDF	Dlaczego pominięta
`setDocCreationTimestamp()` / `setDocModificationTimestamp()`	Stan jest przechowywany w adapterze, ale nie jest powiązany z metadanymi XMP dokumentu. Nie jest widoczny w danych wyjściowych.
`setSRGBmode()`	Zarządzanie kolorami w NextPDF jest niezależne od tej flagi.
`setPDFVersion()`	NextPDF wybiera wersję PDF na podstawie swojego profilu conformance/output; nie ma bezpośredniego settera. Adapter emituje powiadomienie i kontynuuje działanie.
`setDocInfoUnicode()`	NextPDF zawsze używa Unicode; flaga z założenia nie powoduje żadnego działania.
`setDefaultMonospacedFont()`	Brak odpowiednika w silniku; zamiast tego stosuje się stylowanie HTML/CSS.
`setFontSubsetting()`	NextPDF zawsze tworzy podzbiory osadzonych czcionek; flaga jest w praktyce zawsze włączona.

Wersja PDF jest ustalana przez silnik. Dane wyjściowe są zapisywane jako PDF 2.0 (ISO 32000-2). ISO 32000-2 §7.5.2 określa, że zgodny mechanizm zapisujący identyfikuje wersję dokumentu — w nagłówku pliku lub we wpisie Version katalogu — jako 2.0. Określa również, że zapisanie pliku nie obniża jego wersji. Odpowiada to zachowaniu adaptera: wywołania takie jak setPDFVersion('1.4') nie mogą za pośrednictwem tego adaptera obniżyć docelowej wersji PDF do starszej. Skrócone odniesienie do klauzuli znajduje się w sekcji citations we front-matterze strony.

5. Metody z dryfu nowoczesnego API

Siedemnaście metod z rdzenia NextPDF v5.1+ udostępniono w adapterze (cecha AdaptsDriftV51), aby kod łączący API TCPDF z nowoczesnym API nadal się kompilował. Nie mają one odpowiednika w TCPDF 6.x. Przykłady: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). Traktuj je jako nowoczesne API, a nie jako część kontraktu zgodności z TCPDF.

6. Wskazówki dotyczące wycofywania i zastępowania

Jeśli Twój kod wywołuje…	Status	Zrób zamiast tego tak
`Error()`	Zmienione zachowanie (wzmocnione)	Adapter zastępuje `die()` z TCPDF zgłoszeniem wyjątku `RuntimeException`. Opakuj ryzykowne wywołania w `try`/`catch`; nie polegaj na zakończeniu procesu.
`setPDFVersion()`	Nie dotyczy	Usuń. Dane wyjściowe są zawsze w formacie PDF 2.0.
`setUserRights()`	Wycofane w PDF 2.0	Usuń. Wywołanie emituje powiadomienie `E_USER_DEPRECATED` i jest ignorowane.
`setSignature()`	Niezaimplementowane w rdzeniu	Przejdź na nowoczesne API podpisu w edycji komercyjnej.
`Image(...)` z dodatkowymi parametrami	Ciche pomijanie	Ogranicz do file, x, y, w, h; dodaj `Document::link()` dla klikalnych obrazów.
`endPage()` / `Open()`	Niezaimplementowane / brak działania	Usuń.

7. Bezpieczne kroki migracji

Zainstaluj pakiet i uruchom istniejący zestaw testów z adapterem, bez zmian w kodzie. Zobacz /integrations/tcpdf-compat/install/ oraz /integrations/tcpdf-compat/quickstart/.
Włącz tryb ścisły w osobnym przebiegu audytowym (nie w środowisku produkcyjnym): $pdf->setStrictMode(true);. Zbierz każdy TcpdfNotImplementedException. Każdy wyjątek wskazuje dokładne ignorowane parametry oraz wskazówkę migracyjną.
W każdym miejscu zgłoszenia wyjątku zdecyduj, czy porzucić ignorowany parametr, czy przenieść to wywołanie do nowoczesnego API za pomocą $pdf->getDocument().
Ustal nową wartość bazową dla każdego testu sprawdzającego dokładne bajty PDF; zamiast tego sprawdzaj wyrenderowaną treść lub właściwości strukturalne.
Wyłącz tryb ścisły i wdróż zaudytowaną ścieżkę kodu. Utrzymuj okresowe zadanie CI w trybie ścisłym, aby wychwytywać regresje podczas refaktoryzacji.

Pełna procedura z kodem: /integrations/tcpdf-compat/migration/.

Zobacz także

docs/TCPDF_COVERAGE.md — autorytatywna, zweryfikowana testami macierz pokrycia (w repozytorium)
/integrations/tcpdf-compat/migration/ — kompleksowa strategia migracji z TCPDF do NextPDF
/integrations/tcpdf-compat/configuration/ — tryb ścisły i konfiguracja adaptera
/integrations/tcpdf-compat/security-and-operations/ — podejście do szyfrowania i podpisów
/integrations/tcpdf-compat/integration/ — podłączanie adaptera do aplikacji
/integrations/tcpdf-compat/boot-and-discovery/ — rejestracja aliasów klas i udostępnianie fasady