Przewodnik programisty po zgodności z TCPDF

W skrócie

Adapter zgodności jest warstwą migracyjną. Uwidacznia zachowanie starszego kodu, zamiast je ukrywać. Korzystaj z niego, aby utrzymać działanie aplikacji podczas przenoszenia kluczowych ścieżek do natywnych interfejsów API NextPDF.

Korzystaj z tego przewodnika, gdy utrzymujesz starszy kod o interfejsie TCPDF, rozszerzasz pokrycie adaptera albo planujesz etapową migrację do natywnych interfejsów API NextPDF.

Granica architektury

Warstwa	Należy do	Odpowiedzialność	Nie umieszczaj tutaj
Starsza aplikacja	Aplikacja	Utrzymanie działania istniejących wywołań o interfejsie TCPDF podczas migracji.	Nowe funkcje PDF, które powinny korzystać z natywnych interfejsów API NextPDF.
Powłoka adaptera	nextpdf/compat-legacy	Udostępnianie klasy o kształcie TCPDF i współdzielonego stanu zgodności.	Duże rodziny metod lub logika konwersji.
Cechy obszarów odpowiedzialności	nextpdf/compat-legacy	Grupowanie rodzin starszych metod: tekst, czcionki, obrazy, zabezpieczenia, formularze, strony.	Międzyrodzinna polityka wyjścia.
Klasy pomostowe	nextpdf/compat-legacy	Konwersja starszych argumentów, miejsc docelowych, kolorów, jednostek i formatów.	Zachowanie specyficzne dla domeny biznesowej.
Silnik podstawowy	nextpdf/nextpdf	Tworzenie natywnego dokumentu.	Gwarancje zgodności ze starszym kodem.

Cykl życia w czasie wykonywania

Etap	Zachowanie	Działanie programisty
Inicjalizacja	Opcjonalna inicjalizacja dla starszego kodu udostępnia nazwy zgodności.	Używaj jej tylko tam, gdzie starszy kod oczekuje symboli TCPDF.
Konstruowanie	Adapter mapuje starsze argumenty konstruktora na konfigurację dokumentu podstawowego.	Utrzymuj stabilne dane wejściowe konstruktora podczas migracji.
Wywołanie metody	Obsługiwane metody są mapowane na zachowanie NextPDF za pośrednictwem obszarów odpowiedzialności i pomostów.	Sprawdź pokrycie metod, zanim założysz równoważność.
Nieobsługiwana funkcja	Adapter zgłasza jawne wyjątki zgodności dla nieobsługiwanego zachowania.	Zastąp wywołanie lub odizoluj je w kodzie aplikacji.
Wyjście	Pomost wyjścia mapuje zachowanie starszego miejsca docelowego na mechanizm wyjścia NextPDF.	Zweryfikuj nazwy plików i katalogi główne magazynu.

Inwentaryzacja migracji

Zacznij od zebrania wszystkich wywołań metod TCPDF w aplikacji. Sklasyfikuj każde wywołanie, zanim zmienisz jego zachowanie.

Klasyfikacja	Znaczenie	Działanie
Obsługiwana metoda adaptera	Metoda jest udokumentowana jako obsługiwana i ma testy.	Pozostaw ją tymczasowo, a następnie zmigruj, gdy będziesz pracować w tym obszarze.
Częściowo obsługiwana metoda adaptera	Metoda istnieje, ale jej zachowanie nie odpowiada w pełni starszemu TCPDF.	Dodaj testy oparte na danych testowych i ręcznie sprawdź poprawność wyniku.
Jawnie nieobsługiwana metoda	Adapter zgłasza wyjątek zgodności.	Zastąp ją natywnym interfejsem API NextPDF lub usuń tę funkcję.
Otoka specyficzna dla domeny biznesowej	Aplikacja już opakowuje wywołania TCPDF.	Najpierw zmigruj implementację otoki.
Wywołanie wrażliwe z punktu widzenia zgodności	Przepływ podpisu, szyfrowania, tagowania, PDF/A, dostępności lub faktury.	Zmigruj do natywnych interfejsów API NextPDF z dedykowaną weryfikacją.

Wzorzec wkładu do adaptera

Dodaj obsługę zgodności w najmniejszej rodzinie metod odpowiedzialnej za dane zachowanie.

Typ zmiany	Gdzie zaimplementować	Wymagany test
Metoda wyjścia tekstu	Concerns\AdaptsTextOutput lub obszar odpowiedzialności czcionek.	Starsze dane testowe i asercja natywnego wyniku.
Metoda strony lub marginesu	Obszar odpowiedzialności strony, pozycjonowania lub marginesów.	Test konwersji współrzędnych i stanu strony.
Metoda obrazu lub rysunku	Obszar odpowiedzialności obrazów, rysowania, kolorów lub gradientów.	Test walidacji danych wejściowych oraz wyniku visual/structural.
Miejsce docelowe wyjścia	OutputBridge.	Test mapowania miejsca docelowego i niebezpiecznej ścieżki.
Nieobsługiwana funkcja	Fabryka wyjątków lub tabela pokrycia metod.	Test typu wyjątku oraz komunikatu.

Nie umieszczaj dużej metody bezpośrednio w powłoce adaptera, jeśli rodziną zarządza cecha obszaru odpowiedzialności.

Wzorzec natywnej migracji

Użyj adaptera, aby ustabilizować starszy kod, a następnie przenieś stabilne przepływy pracy do natywnych interfejsów API.

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

Traktuj migrację jako sekwencję niewielkich zmian zachowania. Strona może nadal korzystać z adaptera, podczas gdy jedna sekcja wysokiego ryzyka przechodzi na natywne interfejsy API.

Punkty rozszerzeń

Punkt rozszerzenia	Używaj do	Ograniczenie
AdaptationConfig	Sterowanie zachowaniem adaptera podczas migracji.	Utrzymuj wartości domyślne jako jawne i poddane przeglądowi.
Cechy obszarów odpowiedzialności	Grupowanie rodzin metod, takich jak tekst, formularze, obrazy lub zabezpieczenia.	Dodawaj metody do odpowiedniego obszaru odpowiedzialności, a nie do powłoki adaptera.
Klasy pomostowe	Konwersja starszych kształtów argumentów na wartości podstawowe.	Obejmij zachowanie pomostu testami migracji.
CompatAdapterInterface	Abstrakcja na poziomie adaptera dla narzędzi.	Nie używaj jej jako zamiennika natywnych kontraktów podstawowych w nowym kodzie.
Tabela pokrycia metod	Rejestr obsługi dla programistów.	Aktualizuj ją, gdy zmienia się status obsługi.

Przebieg migracji

1. Zainstaluj adapter i uruchom starszy pakiet testów bez zmian.
2. Otwórz pokrycie metod i sklasyfikuj każdą wywoływaną metodę.
3. Najpierw zastąp nieobsługiwane metody.
4. Przenieś ścieżki o dużym natężeniu lub wrażliwe z punktu widzenia zgodności do natywnych podstawowych interfejsów API.
5. Dodaj pokrycie oparte na danych testowych dla każdej zmigrowanej rodziny metod.
6. Usuń aliasy inicjalizacji, gdy żaden punkt wejścia aplikacji od nich nie zależy.

Obsługa awarii

Awaria	Gdzie obsłużyć	Zalecana reakcja
Nieobsługiwana metoda	Wyjątek adaptera.	Zastąp wywołanie lub odizoluj je za adapterem aplikacji.
Częściowa zgodność układu	Testy migracji i przegląd wizualny.	Udokumentuj zaakceptowaną różnicę przed wdrożeniem.
Niebezpieczne miejsce docelowe wyjścia	OutputBridge oraz polityka magazynu aplikacji.	Odrzucaj niebezpieczne ścieżki i preferuj natywne interfejsy API wyjścia.
Niezgodność funkcji zabezpieczeń	Plan natywnej migracji.	Nie wdrażaj dla wyników podlegających regulacjom zachowania dostępnego wyłącznie w trybie zgodności.
Kolizja aliasu inicjalizacji	Inicjalizacja aplikacji.	Usuń globalne aliasy lub ogranicz je do starszych punktów wejścia.

Bezpieczne wartości domyślne

Obszar odpowiedzialności	Wartość domyślna	Kiedy nadpisać
Nieobsługiwane metody	Zgłoszenie jawnego wyjątku.	Nie osłabiaj tego w produkcji.
Starsze wartości domyślne	Scentralizowane w LegacyDefaults.	Nadpisuj tylko dla znanego zachowania migracyjnego.
Mapowanie wyjścia	Przechodzi przez OutputBridge.	Po migracji korzystaj z natywnych interfejsów API wyjścia.
Źródło pokrycia	Strona pokrycia metod i testy.	Uruchamiaj kontrole pokrycia ponownie po każdej aktualizacji adaptera.
Tryb ścisły	Pozostaw włączony podczas audytów migracji.	Wyłączaj tylko na czas udokumentowanego okna zgodności ze starszym kodem.

Lista kontrolna testów

• Zachowaj starsze dane testowe dla każdej zmigrowanej rodziny metod.
• Dodaj jeden natywny test NextPDF, zanim zastąpisz starszą metodę.
• Asercją sprawdzaj, czy nieobsługiwane metody zgłaszają udokumentowany wyjątek.
• Porównuj strukturę wyniku, gdy dokładna równość bajtów nie jest realistycznym celem migracji.
• Uruchamiaj kontrole pokrycia metod po dodaniu lub zmianie metod adaptera.
• Dodaj testy ścieżek magazynu dla każdego miejsca docelowego wyjścia używanego przez starszy kod.