compat-legacy — szybki start

W skrócie

Ta strona prowadzi od zainstalowanego pakietu do gotowego pliku PDF, a następnie do audytu w trybie ścisłym, uruchamianego przed migracją. Każdy blok kodu odpowiada zachowaniu potwierdzonemu przez zestaw testów pakietu, więc pokazane tu dane wyjściowe są tymi samymi danymi, które weryfikują testy.

Zanim zaczniesz

Zainstaluj pakiet i potwierdź powiązanie z silnikiem zgodnie z instrukcją na stronie /integrations/tcpdf-compat/install/. Potrzebujesz PHP 8.4, a zależność nextpdf/core ^3.0 musi zostać rozwiązana.

1. Utwórz pierwszy dokument

Zmień import i pozostaw wywołania w stylu TCPDF. To dokładnie tę powierzchnię API weryfikuje tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

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

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

Uruchom przykład:

php examples/quickstart-first.php

Plik quickstart.pdf jest poprawnym plikiem PDF 2.0. Zestaw testów potwierdza, że odpowiednie dane wyjściowe zwrócone jako łańcuch znaków zaczynają się od %PDF dla miejsc docelowych S, F i E oraz dla getPDFData().

Miejsca docelowe danych wyjściowych

Output($name, $dest) mapuje kody miejsc docelowych TCPDF za pośrednictwem bezpiecznego mostka wyjściowego. Zestaw testów sprawdza to zachowanie:

`$dest`	Zachowanie	Zwraca
`'S'`	Zwraca PDF jako łańcuch znaków	Bajty PDF (`%PDF…`)
`'F'`	Zapisuje PDF do podanej ścieżki	pusty łańcuch znaków
`'E'`	Zwraca treść MIME w kodowaniu base64	blok `Content-Type: application/pdf`
`'I'`	W treści odpowiedzi (domyślnie)	zgodnie z mostkiem wyjściowym
`'D'`	Pobranie pliku	zgodnie z mostkiem wyjściowym

W odróżnieniu od starszego TCPDF Output() nie wypisuje danych bezpośrednio do aktywnego bufora wyjściowego. Tę metodę można bezpiecznie wywołać wewnątrz procesu roboczego kolejki lub procedury obsługi HTTP, która kontroluje własną odpowiedź. Zobacz /integrations/tcpdf-compat/production-usage/.

2. Uruchom istniejący kod TCPDF bez zmian

W przypadku rzeczywistej migracji zacznij od uruchomienia istniejącego kodu, zmieniając jedynie import lub alias. Jeśli baza kodu wywołuje new \TCPDF(...) w globalnej przestrzeni nazw, włącz opcjonalne aliasy raz podczas rozruchu (opisane w /integrations/tcpdf-compat/boot-and-discovery/):

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

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

LegacyBootstrap::enableAliases() jest idempotentne. Rejestruje \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS i \TCPDF_IMAGES tylko wtedy, gdy te klasy jeszcze nie istnieją. Test pakietu tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php potwierdza rejestrację aliasów, idempotentność wywołania oraz to, że new \TCPDF() jest instancją adaptera. Nie włączaj aliasów, jeśli w tym samym procesie jest załadowana prawdziwa biblioteka TCPDF; zobacz /integrations/tcpdf-compat/troubleshooting/.

3. Przeprowadź audyt w trybie ścisłym

Ten krok sprawia, że migracja jest bezpieczniejsza. Przy wyłączonym trybie ścisłym (ustawienie domyślne) metody, które nie potrafią odtworzyć zachowania TCPDF, działają w sposób zdegradowany bez ostrzeżenia. Przy włączonym trybie ścisłym zgłaszają TcpdfNotImplementedException z dokładnie wskazanymi pominiętymi parametrami. Uruchamiaj ten tryb w dedykowanym przebiegu audytowym, nigdy w środowisku produkcyjnym.

<?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 {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

Test pakietu tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php potwierdza, że to konkretne wywołanie zgłasza wyjątek w trybie ścisłym, nie generuje komunikatu w trybie domyślnym oraz że komunikat zawiera nazwę metody i pominięte parametry. Wykorzystaj zebrane wyjątki jako listę zadań migracyjnych — zobacz /integrations/tcpdf-compat/migration/.

4. Sięgnij po nowoczesne API, gdy jest potrzebne

Każda instancja adaptera udostępnia bazowy dokument silnika. Użyj tego dokumentu, aby wywoływać nowoczesne metody NextPDF, które nie mają odpowiednika w TCPDF:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument() zwraca obiekt NextPDF\Core\Document, który opakowuje adapter. To zalecana ścieżka wyjścia: przenoś miejsca wywołań do nowoczesnego API pojedynczo, aż możliwe będzie usunięcie adaptera.

Różnice w zachowaniu, których należy się od razu spodziewać

MultiCell() zwraca 1, a nie liczbę wyrenderowanych komórek. Kod, który rozgałęzia się na podstawie wartości zwracanej przez MultiCell(), wymaga dostosowania.
Error() zgłasza RuntimeException zamiast wywoływać die(). Kod, który polegał na zakończeniu procesu, musi przechwytywać ten wyjątek.
Dokładne bajty PDF różnią się od danych wyjściowych TCPDF. Wyznacz na nowo bazę odniesienia dla asercji testowych na poziomie bajtów, tak aby zamiast tego sprawdzały wyrenderowaną treść.

Pełna lista z podziałem na metody znajduje się w /integrations/tcpdf-compat/method-coverage/.

Następne kroki

/integrations/tcpdf-compat/migration/ — pełna strategia migracji, plik po pliku.
/integrations/tcpdf-compat/configuration/ — tryb ścisły, ustawienia domyślne i nowoczesny obiekt konfiguracji.
/integrations/tcpdf-compat/production-usage/ — procesy robocze, bufory wyjściowe i wydajność.
/integrations/tcpdf-compat/security-and-operations/ — podejście do szyfrowania i podpisywania.

Zobacz także

tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — źródło prawdy dla zachowania danych wyjściowych
tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — źródło prawdy dla trybu ścisłego
docs/TCPDF_COVERAGE.md — miarodajna macierz pokrycia