Dokumentacja API zgodności z TCPDF

W skrócie

Główną klasą pakietu nextpdf/compat-legacy jest NextPDF\Compat\Tcpdf\TCPDF. Odwzorowuje publiczne API (interfejs programowania aplikacji) TCPDF 6.x, ale renderuje dokumenty za pomocą nowoczesnego silnika NextPDF. Pakiet obejmuje też niewielki zestaw funkcji pomocniczych: LegacyBootstrap do globalnych aliasów klas, powierzchnię konfiguracji AdaptationConfig/LegacyDefaults, wewnętrzne klasy mostków do obsługi wyjścia, konstrukcji, koloru, jednostek i formatów stron oraz wyjątki zgodności. Traktuj go jako narzędzie wspierające migrację, a nie jako trwałą zależność. Pełny status metod ze starszego API znajdziesz w tabeli pokrycia metod. Ta strona dokumentuje wyłącznie powierzchnie, na których kod aplikacji powinien świadomie polegać.

Zacznij tutaj: Jeśli dopiero zaczynasz pracę z tym pakietem, utwórz NextPDF\Compat\Tcpdf\TCPDF, użyj standardowych wywołań TCPDF (AddPage(), SetFont(), Cell()) i zakończ wywołaniem Output($name, $dest). Ta klasa jest punktem wejścia do niemal wszystkiego, co opisano poniżej. Gotowe punkty startowe znajdziesz w sekcji Typowe zadania.

Typowe zadania

Oto zadania, z których w tym pakiecie będziesz korzystać najczęściej. Każdy blok jest zweryfikowany względem źródła adaptera i działa bez zmian.

Utwórz plik PDF (Portable Document Format) za pomocą znanych wywołań TCPDF, a następnie przechwyć go jako ciąg znaków do kolejki, odpowiedzi HTTP lub magazynu:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetTitle('Invoice 1234');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$bytes = $pdf->Output('invoice.pdf', 'S');

Co robi: tworzy dokument PDF 2.0 za pomocą adaptera odwzorowującego kształt TCPDF. Zwraca surowe bajty (%PDF...), ponieważ miejsce docelowe 'S' kieruje przez OutputBridge do Document::getPdfData() zamiast wypisywać dane na wyjście, więc jest bezpieczne wewnątrz procesu roboczego lub kontrolera.

Zarejestruj globalne aliasy raz podczas uruchamiania, aby uruchomić istniejący kod new \TCPDF(...) bez edycji kodu źródłowego:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/legacy.pdf', 'F');

Co robi: enableAliases() w sposób idempotentny rejestruje \TCPDF (oraz funkcje pomocnicze \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES) tylko wtedy, gdy te nazwy nie są jeszcze zdefiniowane. Dzięki temu niezmieniony starszy kod działa na adapterze.

Skontroluj migrację, ujawniając każdy parametr TCPDF, który adapter w przeciwnym razie pominąłby po cichu:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter
}

Co robi: przy włączonym setStrictMode(true) wywołanie, które nie może odtworzyć zachowania TCPDF, zgłasza TcpdfNotImplementedException i wymienia każdy pominięty parametr. Dzięki temu ciche obniżenie jakości staje się listą zadań migracyjnych. Włączaj ten tryb tylko podczas przeglądu kontrolnego, nigdy w środowisku produkcyjnym.

Główny adapter

Ta tabela opisuje kanoniczną powierzchnię adaptera. Użyj jej, aby znaleźć klasę, którą tworzysz (TCPDF), jej metody trybu ścisłego i wyjścia awaryjnego oraz kontrakt, który implementuje.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza / kończy się niepowodzeniem	Uwagi
NextPDF\Compat\Tcpdf\TCPDF	Parametry konstruktora zachowują postać starszego TCPDF za pośrednictwem ConstructorBridge.	Tworzy adapter oparty na dokumencie NextPDF.	TCPDF	Wyjątki walidacji konstruktora albo nieobsługiwanej funkcji.	Używaj podczas migracji, a nie w nowym natywnym kodzie NextPDF.
TCPDF::getDocument()	brak.	Zwraca bazowy dokument NextPDF.	NextPDF\Core\Document	nie oczekuje się.	Używaj jako wyjścia awaryjnego dla kodu migracyjnego, który musi łączyć wywołania starsze i natywne.
TCPDF::getUnitConverter()	brak.	Zwraca konwerter utworzony na podstawie starszej jednostki.	UnitConverter	nie oczekuje się.	Używaj do diagnostyki migracji, a nie w zwykłym kodzie aplikacji.
TCPDF::setStrictMode(bool $enabled)	Flaga trybu ścisłego.	Włącza lub wyłącza jawne niepowodzenie przy nieobsługiwanym zachowaniu zgodności.	static	nie oczekuje się.	Pozostaw włączone podczas przeglądów kontrolnych migracji.
TCPDF::isStrictMode()	brak.	Zwraca bieżącą flagę trybu ścisłego.	bool	nie oczekuje się.	Przydatne w asercjach testowych.
Metody ze starszego API klasy TCPDF	Zależy od metody.	Obsługiwane metody są mapowane na wywołania dokumentu rdzenia; nieobsługiwane metody kończą się jawnym niepowodzeniem.	Zależy od metody.	TcpdfNotImplementedException lub UnsupportedFeatureException.	Sprawdź pokrycie metod, zanim zaczniesz polegać na danej metodzie.
CompatAdapterInterface::getDocument()	brak.	Metoda kontraktu zaimplementowana przez TCPDF.	Document	nie oczekuje się.	Pozwala narzędziom dotrzeć do natywnego dokumentu.
CompatAdapterInterface::Output(string $name = '', string $dest = '')	Nazwa pliku i starsze miejsce docelowe.	Deleguje do mostka wyjścia.	string	Błędy zapisu rdzenia lub nieobsługiwanego miejsca docelowego.	Odwzorowuje wyjście starszego TCPDF; konkretna metoda TCPDF::Output dostarcza wartości domyślne 'doc.pdf'/'I'.

Grupy metod starszego API

Ta tabela mapuje rodziny metod TCPDF objęte przez adapter. Przejrzyj ją, aby zlokalizować starsze wywołanie, zanim sprawdzisz jego dokładny status w pokryciu metod.

Grupa	Reprezentatywne symbole	Zachowanie domyślne	Uwagi
Cykl życia i wyjście	Open(), Close(), Output(), getPDFData()	Zachowuje cykl życia dokumentu w stylu TCPDF na natywnym dokumencie.	Po migracji preferuj natywne API wyjścia.
Metadane	SetTitle(), SetAuthor(), SetSubject(), SetKeywords(), SetCreator()	Mapuje settery metadanych na dokument bazowy.	Normalizację metadanych pozostaw w kodzie aplikacji.
Strony i pozycjonowanie	AddPage(), setPage(), lastPage(), GetX(), SetXY()	Konwertuje starsze jednostki i współrzędne na natywne operacje na stronach.	Po migracji zweryfikuj pozycjonowanie bezwzględne wizualnie.
Marginesy i układ	SetMargins(), SetAutoPageBreak(), setCellPaddings(), getMargins()	Przechowuje stan zgodności i mapuje obsługiwane wartości.	Złożone zachowanie podziału stron w TCPDF może wymagać ręcznego przeglądu.
Czcionki i tekst	SetFont(), AddFont(), Cell(), MultiCell(), Write(), Text()	Kieruje typowe operacje na tekście do natywnych API czcionek i tekstu.	Sprawdź zachowanie CJK i kodowania z czcionkami produkcyjnymi.
HTML	writeHTML(), writeHTMLCell(), fixHTMLCode()	Przekazuje obsługiwany kod HTML do natywnego potoku HTML.	Natywny renderer nie jest pełnym klonem obsługi HTML z TCPDF.
Obrazy i rysowanie	Image(), Line(), Rect(), Circle(), SetDrawColor()	Mapuje obsługiwane operacje graficzne za pomocą funkcji adaptera.	Nieobsługiwane formaty wektorowe lub specjalne kończą się jawnym niepowodzeniem.
Nawigacja i adnotacje	Bookmark(), AddLink(), SetLink(), Annotation()	Zachowuje typowe wywołania nawigacyjne tam, gdzie istnieje mapowanie.	Zweryfikuj wygenerowane konspekty i odnośniki.
Bezpieczeństwo i podpisy	SetProtection(), setSignature(), setTimeStamp(), setUserRights()	Łączy obsługiwane starsze wywołania bezpieczeństwa z natywnymi funkcjami.	Wyjście kryptograficzne traktuj jako osobną bramkę weryfikacji.
Formularze, szablony, przekształcenia	TextField(), startTemplate(), StartTransform(), Rotate(), Scale()	Implementuje obsługiwane podzbiory, a przy nieobsługiwanym zachowaniu kończy się głośnym niepowodzeniem.	Przed wdrożeniem skontroluj każde wywołanie względem pokrycia metod.

Bootstrap i konfiguracja

Skorzystaj z tej tabeli, gdy podłączasz adapter do ścieżki startowej aplikacji, rejestrujesz globalne aliasy lub wybierasz między starszymi stałymi a nowoczesną klasą AdaptationConfig.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza / kończy się niepowodzeniem	Uwagi
LegacyBootstrap::enableAliases()	brak.	Rejestruje aliasy zgodności tylko raz.	void	Błędy automatycznego ładowania lub środowiska.	Używaj tylko wtedy, gdy starszy kod oczekuje, że nazwy TCPDF istnieją globalnie.
LegacyBootstrap::isRegistered()	brak.	Informuje, czy aliasy zostały zarejestrowane.	bool	nie oczekuje się.	Przydatne w testach bootstrapu.
LegacyBootstrap::resetForTesting()	brak.	Czyści stan rejestracji na potrzeby testów.	void	nie oczekuje się.	Funkcja pomocnicza tylko do testów.
AdaptationConfig	Flagi adaptera i kontrolki migracji.	W przypadku pominięcia używa wartości domyślnych pakietu.	AdaptationConfig	Nieprawidłowe wartości opcji.	Podczas przeglądów kontrolnych migracji zachowaj jawną konfigurację.
AdaptationConfig::fromLegacyConstants()	brak.	Odczytuje znane starsze stałe i tworzy obiekt konfiguracji.	AdaptationConfig	Nieprawidłowe wartości starszych stałych.	Przejściowa funkcja pomocnicza dla dużych starszych aplikacji.
LegacyDefaults	brak.	Udostępnia domyślne wartości starszego API.	Wartości domyślne.	nie oczekuje się.	Centralne miejsce przechowywania domyślnych wartości zgodności.

Mostki i funkcje pomocnicze

Te wewnętrzne klasy konwersji obsługują działanie adaptera. Skorzystaj z tej tabeli, gdy współtworzysz pokrycie adaptera lub diagnozujesz, jak przełożono starszy argument. W codziennym kodzie aplikacji preferuj publiczną powierzchnię adaptera.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza / kończy się niepowodzeniem	Uwagi
ConstructorBridge	Lista argumentów starszego konstruktora.	Normalizuje starsze opcje do postaci konfiguracji NextPDF.	Dane konstruktora.	Nieprawidłowe wartości starszych argumentów.	Używane wewnętrznie przez adapter.
CellParameterAdapter	Parametry komórki TCPDF.	Mapuje starsze argumenty pozycyjne na opcje układu tekstu rdzenia.	Zaadaptowane parametry.	Nieprawidłowe wymiary lub wyrównanie.	W nowym kodzie preferuj natywne metody rdzenia.
OutputBridge::dispatch(Document $document, string $filename, string $dest)	Natywny dokument, nazwa pliku i starsze miejsce docelowe.	Mapuje zachowanie inline/download/save na API wyjścia NextPDF.	string	Błędy zapisu rdzenia; nieobsługiwane miejsce docelowe.	Przed wyjściem zweryfikuj nazwy plików i katalogi główne magazynu.
OutputBridge::resolveDestination(string $dest)	Kod starszego miejsca docelowego.	Konwertuje je na natywne miejsce docelowe wyjścia.	OutputDestination	Błędy nieobsługiwanego miejsca docelowego.	Utrzymuje scentralizowane mapowanie miejsc docelowych.
ColorTranslator	Argumenty koloru TCPDF.	Normalizuje starsze formy koloru.	Wartość koloru rdzenia.	Nieprawidłowe wartości koloru.	Używane przez funkcje koloru i rysowania.
PageFormatResolver	Dane wejściowe starszego formatu strony.	Mapuje znane nazwy na rozmiary stron rdzenia.	Wartość formatu strony.	Nieznany format.	Po migracji używaj jawnych natywnych rozmiarów stron.
UnitConverter	Starsze wartości miar i jednostki.	Konwertuje na jednostki rdzenia.	Wartość liczbowa.	Nieprawidłowa jednostka.	Pomaga zachować zachowanie układu znane ze starszego API.

Wyjątki

Skorzystaj z tej tabeli, gdy wywołanie w ramach migracji kończy się głośnym niepowodzeniem. Tabela rozróżnia niepowodzenia „niezaimplementowane” oraz „znane, lecz nieobsługiwane” i pokazuje ścieżkę odzyskiwania.

Symbol	Znaczenie	Odzyskiwanie
TcpdfNotImplementedException	Adapter celowo nie implementuje żądanej metody ze starszego API.	Zastąp wywołanie natywnym API NextPDF lub usuń zależność.
TcpdfNotImplementedException::forSilentIgnore()	Starsze wywołanie zostałoby wcześniej zignorowane, ale teraz jest ujawniane dla przejrzystości migracji.	Zdecyduj, czy jawne zachowanie „bez operacji” jest akceptowalne.
TcpdfNotImplementedException::forUnimplemented()	Dla starszego wywołania nie ma zaimplementowanej ścieżki adaptera.	Zastąp wywołanie lub odizoluj je w kodzie migracyjnym.
UnsupportedFeatureException	Starsza funkcja jest znana, ale nieobsługiwana w granicach adaptera.	Sprawdź wskazówki dotyczące migracji i odizoluj funkcję za adapterem aplikacji.
UnsupportedFeatureException::forMethod()	Tworzy specyficzny dla metody błąd nieobsługiwanej funkcji.	Używaj w zmianach rozwijających zgodność, aby zachować spójne komunikaty o niepowodzeniach.

Uwagi programistyczne

• Traktuj adapter jako narzędzie migracji. Nowy kod powinien bezpośrednio korzystać z natywnych API rdzenia NextPDF.
• Nieobsługiwane zachowanie powinno powodować głośne niepowodzenie. Nie przechwytuj wyjątków zgodności i nie kontynuuj z częściowym dokumentem, chyba że aplikacja jawnie akceptuje to ryzyko.
• Wprowadzaj małe zmiany migracyjne i weryfikuj każdą starszą metodę względem tabeli pokrycia.