Uruchamianie i wykrywanie NextPDF compat-legacy

W skrócie

nextpdf/compat-legacy udostępnia NextPDF\Compat\Tcpdf\TCPDF — fasadę zgodną z TCPDF, która deleguje zadania do silnika NextPDF. Jest to warstwa zgodności, a nie klon mający działać jako bezpośredni zamiennik. Deleguje bezpośrednio 94 z około 120 przeanalizowanych metod TCPDF 6.x. Dla pozostałych metod udokumentowano różnice w działaniu; zobacz /integrations/tcpdf-compat/method-coverage/.

Brak globalnego wiązania podczas autoładowania. Dodanie pakietu domyślnie nie tworzy globalnej klasy \TCPDF. Globalne aliasy włącza się jawnie albo — co jest zalecane podczas migracji — importuje klasę adaptera osobno w każdym pliku.

Jak udostępniana jest fasada TCPDF

Fasada to standardowa klasa autoładowana zgodnie z PHP Standard Recommendation 4 (PSR-4):

Pozycja	Wartość
Klasa fasady	NextPDF\Compat\Tcpdf\TCPDF
Prefiks PSR-4	NextPDF\Compat\Tcpdf\ odwzorowuje się na src/Compat/Tcpdf/
Wspólny kontrakt	NextPDF\Compat\Contracts\CompatAdapterInterface
Furtka awaryjna	TCPDF::getDocument() zwraca opakowany obiekt NextPDF\Core\Document

Klasa celowo nie jest final. Użytkownicy starszego TCPDF często tworzą podklasy TCPDF, aby nadpisać Header() i Footer(), a adapter zachowuje ten punkt rozszerzenia. Wewnętrznie klasa działa jako fasada. Składa się z 25 cech (traits) o pojedynczej odpowiedzialności i deleguje wszystkie operacje związane z formatem Portable Document Format (PDF) do instancji Document tworzonej podczas budowania fasady.

Sekwencja uruchamiania

Diagram

Wywołanie konstruktora to jedyny krok „uruchamiania”. Sam pakiet nie rejestruje żadnego kontenera usług ani nie wykonuje inicjalizacji frameworka. Integrację z frameworkiem dodaje się jako cienką warstwę; zobacz /integrations/tcpdf-compat/integration/.

LegacyDefaults::register() działa idempotentnie: definiuje stałą tylko wtedy, gdy nie została jeszcze zdefiniowana. Stałe zdefiniowane przez aplikację zawsze mają pierwszeństwo, jeśli zostaną zdefiniowane przed pierwszą konstrukcją; zobacz /integrations/tcpdf-compat/configuration/ § Kolejność rozwiązywania konfiguracji.

Dobrowolne globalne aliasy klas

Jeśli baza kodu wywołuje new \TCPDF(...) w globalnej przestrzeni nazw, a tych miejsc wywołań nie można jeszcze zmienić, zarejestruj globalne aliasy jednorazowo podczas uruchamiania aplikacji:

examples/boot-aliases.php

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() rejestruje \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS oraz \TCPDF_IMAGES. tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php potwierdza to zachowanie:

• Działa idempotentnie: dwukrotne wywołanie nie zgłasza wyjątku i rejestruje aliasy tylko raz.
• LegacyBootstrap::isRegistered() informuje, czy rejestracja została już wykonana.
• Po rejestracji new \TCPDF() tworzy instancję adaptera.

Unikanie konfliktów z rzeczywistą instalacją TCPDF

To najważniejsza zasada na tej stronie.

enableAliases() rejestruje alias tylko wtedy, gdy nie istnieje już klasa o tej nazwie (class_exists($alias, autoload: false)). Dlatego:

• Jeśli zainstalowano tecnickcom/tcpdf, a jego \TCPDF ładuje się jako pierwsze, alias zostaje po cichu pominięty, a kod nadal używa starszego TCPDF zamiast adaptera.
• Uruchamianie obu bibliotek z włączonymi globalnymi aliasami w tym samym procesie nie jest obsługiwane i prowadzi do niejednoznacznego zachowania.

Podczas migracji preferuj jawne importy w każdym pliku (use NextPDF\Compat\Tcpdf\TCPDF;). Łatwo je wyszukać i są jednoznaczne. Usuń tecnickcom/tcpdf, gdy audyt w trybie ścisłym zakończy się powodzeniem; zobacz /integrations/tcpdf-compat/migration/ etap 5. Gdy \TCPDF wskazuje niewłaściwą klasę, diagnostykę znajdziesz w /integrations/tcpdf-compat/troubleshooting/.

Powiązania kontenera

Pakiet nie dostarcza powiązań z kontenerem frameworka. Jeśli fasada jest wiązana w kontenerze, powiąż fabrykę, która zwraca nową instancję NextPDF\Compat\Tcpdf\TCPDF dla każdego dokumentu. Stan dokumentu należy do konkretnej instancji i nie wolno go współdzielić między niepowiązanymi dokumentami; zobacz /integrations/tcpdf-compat/production-usage/ § Współbieżność. Strona /integrations/tcpdf-compat/integration/ pokazuje typowe powiązanie.

Kolejność rozwiązywania konfiguracji

Podczas konstrukcji adapter rozwiązuje konfigurację w tej kolejności: najpierw argumenty konstruktora, następnie wszystkie istniejące starsze stałe zdefiniowane przez aplikację, a na końcu wartości domyślne LegacyDefaults z TCPDF 6.2.13 dla każdej stałej, która nie jest jeszcze zdefiniowana. Pełne szczegóły oraz nowoczesny obiekt AdaptationConfig opisano w /integrations/tcpdf-compat/configuration/.

Diagnostyka

Aby potwierdzić, że fasada jest podłączona, a połączenie z silnikiem działa, utwórz adapter, wygeneruj jednostronicowy plik PDF i sprawdź prefiks %PDF. Testy wyjścia pakietu potwierdzają ten sam zakres zachowania. Gotowy do uruchomienia test znajduje się w /integrations/tcpdf-compat/install/ § Weryfikacja instalacji.

Aby wykryć konflikt z rzeczywistym TCPDF przed włączeniem aliasów, sprawdź, czy globalna klasa \TCPDF już istnieje w miejscu wywołania enableAliases(). Jeśli istnieje, alias zostanie pominięty. Rozwiąż konflikt za pomocą jawnych importów lub usuń rzeczywisty TCPDF, zanim kod zacznie polegać na adapterze.

Pokrycie API TCPDF

Autorytatywną, zweryfikowaną testami macierz pokrycia stanowi plik w repozytorium docs/TCPDF_COVERAGE.md. Podsumowanie dla czytelników, w tym listy metod ignorowanych po cichu i niezaimplementowanych, znajduje się w /integrations/tcpdf-compat/method-coverage/. Pakiet nie przedstawia się jako „bezpośredni zamiennik” ani jako „w 100% zgodny z TCPDF”; jest alternatywą zgodną z TCPDF o znanym, przetestowanym zakresie zgodności i udokumentowanych różnicach w działaniu.

Zobacz także

• docs/TCPDF_COVERAGE.md — autorytatywne źródło informacji o pokryciu (w repozytorium)
• /integrations/tcpdf-compat/integration/ — podłączenie fasady do aplikacji lub frameworka
• /integrations/tcpdf-compat/method-coverage/ — działanie poszczególnych metod i luki
• /integrations/tcpdf-compat/migration/ — etapowa strategia migracji
• /integrations/tcpdf-compat/troubleshooting/ — diagnozowanie konfliktu alias/real-TCPDF
• tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — źródło prawdy o zachowaniu aliasów