Przegląd NextPDF compat-legacy

W skrócie

nextpdf/compat-legacy to alternatywa zgodna z TCPDF: warstwa zgodności, która udostępnia publiczne API TCPDF 6.x w silniku NextPDF dla formatu Portable Document Format (PDF) 2.0. Ma jedno zadanie: sprawić, aby kod zależny już od TCPDF 6.x działał w silniku NextPDF bez przepisywania, co pozwala migrować plik po pliku, a nie wszystko naraz.

To nie jest fork TCPDF ani gwarantowana kopia zachowania TCPDF. To niezależna implementacja, która zachowuje sygnatury wywołań TCPDF. Dokładny opis brzmi tak: obejmuje 94 spośród około 120 zbadanych metod TCPDF 6.x przez bezpośrednie delegowanie, a pozostałe metody mają udokumentowane różnice w zachowaniu (zobacz /integrations/tcpdf-compat/method-coverage/).

Czym jest

• Pomoc w migracji. Pakiet należy do rodziny compat NextPDF. Pomaga odejść od starszej biblioteki PDF; nie powinien stać się trwałą zależnością. Traktuj go jak rusztowanie, usuwane w miarę przechodzenia na nowoczesne API.
• Adapter powierzchni API. Udostępnia nazwę klasy TCPDF, nazwy metod, kolejność parametrów oraz wartości domyślne z wersji 6.2.13. Deleguje wywołania do instancji NextPDF\Core\Document.
• Niezależna implementacja typu clean-room. Ten pakiet nie kopiuje ani nie przekształca kodu źródłowego TCPDF, artefaktów kompilacji, danych czcionek ani innych wyrażeń podlegających prawu autorskiemu. Używa nazwy TCPDF wyłącznie do wskazania interoperacyjności. Wiążące oświadczenie znajduje się w pliku NOTICE pakietu.

Czym nie jest

• Nie jest „zamiennikiem typu drop-in” dającym wynik identyczny bajt po bajcie. W przypadku metod delegowanych widoczny wynik jest zgodny, ale wyrenderowane bajty PDF się różnią, ponieważ pod spodem działa odrębna, niezależna implementacja PDF 2.0.
• Nie jest „w 100% zgodny z TCPDF”. Określony zbiór metod przyjmuje starsze parametry, których silnik nie uwzględnia, albo nie wykonuje żadnych działań. Metody te są wyliczone i przetestowane — zobacz /integrations/tcpdf-compat/method-coverage/.
• Sam w sobie nie jest produktem do podpisywania ani archiwizacji. Podpisy cyfrowe oraz zgodność archiwalna PDF/A są dostępne wyłącznie w komercyjnej edycji NextPDF. Niniejsza dokumentacja nie zawiera żadnych zapewnień o certyfikowanym, gwarantowanym ani prawnie ważnym podpisie.

Dlaczego migrować przez warstwę zgodności

Przepisanie każdego wywołania TCPDF w dużej aplikacji jest ryzykowne i trudne do stopniowego wdrażania. Warstwa zgodności pozwala:

1. Podmienić zależność, a następnie uruchomić istniejący zestaw testów, aby ustalić, co działa bez zmian.
2. Użyć trybu ścisłego jako audytu, który wskazuje każde miejsce, gdzie nie da się dokładnie odtworzyć zachowania TCPDF.
3. Migrować te miejsca wywołań do nowoczesnego API NextPDF pojedynczo, tak aby aplikacja przez cały czas pozostawała gotowa do wdrożenia.

Stan docelowy to nowoczesne API NextPDF\Core\Document bez warstwy zgodności. Pełną strategię znajdziesz w /integrations/tcpdf-compat/migration/.

Co zyskujesz w silniku NextPDF

Gdy adapter deleguje wywołanie TCPDF, jest ono obsługiwane przez silnik PDF 2.0 (ISO 32000-2) z dostępnym szyfrowaniem Advanced Encryption Standard (AES)-256 w standardowym handlerze oraz bezpieczeństwem typów na poziomie PHPStan Level 10 w całym adapterze. Wynik jest zawsze zapisywany jako PDF 2.0; adapter nie może obniżyć wersji docelowej do starszych wersji PDF (zobacz /integrations/tcpdf-compat/method-coverage/ §4).

Adapter wzmacnia kilka historycznych zachowań TCPDF 6.2.13:

Zachowanie starszej wersji	Zachowanie adaptera
Error() wywołuje die() i po cichu kończy proces	Error() zgłasza RuntimeException — wyjątek jest obserwowalny i możliwy do przechwycenia
Metoda HTML, która mogła wykonywać kod PHP ze znaczników	Ta furtka jest wyłączona — znaczniki nie mogą wyzwolić wykonania PHP
Output() wysyła dane bezpośrednio i może uszkodzić bufory wyjściowe procesów roboczych	Wyjście przechodzi przez bezpieczny mostek docelowy
Niezabezpieczona rekurencja header/footer	Zabezpieczona przed rekurencją

Zakres i edycje

Warstwa zgodności jest dostarczana w dystrybucji core (nextpdf/compat-legacy, wymagającej nextpdf/core ^3.0). Szyfrowanie przez standardowy handler jest dostępne w core. Podpisy cyfrowe oraz zgodność archiwalna PDF/A wymagają komercyjnej edycji NextPDF; adapter udostępnia punkty wejścia, ale ścieżka core nie jest produktem do podpisywania. Pełne oświadczenie znajdziesz w /integrations/tcpdf-compat/security-and-operations/.

Dokąd dalej

• /integrations/tcpdf-compat/install/ — zainstaluj pakiet i zweryfikuj połączenie z silnikiem.
• /integrations/tcpdf-compat/quickstart/ — utwórz pierwszy uruchamialny dokument objęty testami.
• /integrations/tcpdf-compat/method-coverage/ — sprawdź dokładnie, co w tej warstwie robi każda metoda TCPDF.
• /integrations/tcpdf-compat/migration/ — zaplanuj strategię migracji plik po pliku.
• /integrations/tcpdf-compat/configuration/ — skonfiguruj tryb ścisły i ustawienia adaptera.
• /integrations/tcpdf-compat/production-usage/ — uruchom adapter pod obciążeniem i w procesach roboczych.
• /integrations/tcpdf-compat/security-and-operations/ — przejrzyj szyfrowanie, podejście do podpisywania oraz wzmacnianie zabezpieczeń.
• /integrations/tcpdf-compat/troubleshooting/ — napraw typowe niepowodzenia migracji.
• /integrations/tcpdf-compat/integration/ / /integrations/tcpdf-compat/boot-and-discovery/ — podłącz fasadę do aplikacji i zarejestruj globalne aliasy klas.

Zobacz też

• docs/TCPDF_COVERAGE.md — wiążąca macierz pokrycia (w repozytorium)
• Plik NOTICE pakietu — oświadczenie o niezależnej implementacji