Integracja z NextPDF compat-legacy

W skrócie

Użyj nextpdf/compat-legacy, aby podłączyć aplikację tak, by istniejący kod TCPDF 6.x działał na silniku NextPDF. Pakiet jest pomocą w migracji, a nie trwałą warstwą pośrednią — usuń go po przejściu na nowoczesne API (zobacz /integrations/tcpdf-compat/migration/). To alternatywa zgodna z TCPDF, a nie zgodny klon: 94 ze ~120 przeanalizowanych metod TCPDF deleguje bezpośrednio. Pozostałe metody mają udokumentowane różnice w zachowaniu (zobacz /integrations/tcpdf-compat/method-coverage/).

Instalacja

composer require nextpdf/compat-legacy:^3.0

Spowoduje to rozwiązanie przechodniej zależności nextpdf/core ^3.0. Pełne wymagania i kroki weryfikacyjne opisano w /integrations/tcpdf-compat/install/.

Inicjalizacja i automatyczne wykrywanie

Pakiet nie rejestruje zmiennych globalnych podczas automatycznego ładowania. Samo dołączenie pakietu nie tworzy globalnej klasy \TCPDF. To Ty decydujesz, w jaki sposób miejsca wywołania odwołują się do tej klasy:

Zalecane (jawne importy). W każdym pliku zmień wiersze use/require na use NextPDF\Compat\Tcpdf\TCPDF;. Takie podejście jest jednoznaczne i łatwe do wyszukania.
Opcjonalne aliasy globalne. Wywołaj LegacyBootstrap::enableAliases() raz podczas inicjalizacji, aby zarejestrować \TCPDF oraz cztery klasy pomocnicze — tylko jeśli te nazwy nie są już zajęte. Mechanizm, idempotentność i regułę konfliktu z prawdziwym TCPDF opisano w /integrations/tcpdf-compat/boot-and-discovery/.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

// One call at application bootstrap, before any \TCPDF use.
LegacyBootstrap::enableAliases();

Powiązania w kontenerze

Pakiet nie zawiera dostawcy usług ani bundle’a dla frameworka. To Ty odpowiadasz za lekką warstwę integracyjną. Powiąż fabrykę, która zwraca nowy adapter dla każdego dokumentu — nigdy współdzielonego singletona, ponieważ każda instancja przechowuje własny stan dokumentu (zobacz /integrations/tcpdf-compat/production-usage/ § Concurrency).

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use Psr\Container\ContainerInterface;

// Pseudocode for a PSR-11-style container: bind a factory, not a shared instance.
$container->set(TCPDF::class, static function (ContainerInterface $c): TCPDF {
    return new TCPDF('P', 'mm', 'A4');
});

// Each resolution is an independent document context.
$pdf = $container->get(TCPDF::class);

W Symfony zarejestruj fabrykę jako usługę niewspółdzieloną. W Laravel użyj bind (a nie singleton), aby przy każdym rozwiązaniu zależności powstawała nowa instancja. Sam pakiet pozostaje niezależny od frameworka.

Publikowanie konfiguracji

Pakiet nie udostępnia publikowalnego pliku konfiguracyjnego frameworka. Skonfiguruj adapter za pomocą starszych stałych K_* / PDF_* (zdefiniuj je w kodzie inicjalizacyjnym przed utworzeniem pierwszej instancji) albo za pomocą nowoczesnego, niezmiennego obiektu NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Zobacz /integrations/tcpdf-compat/configuration/.

Test dymny dostawcy usług / bundle’a

Po podłączeniu sprawdź, czy integracja tworzy prawidłowy plik w formacie Portable Document Format (PDF). Taki test odzwierciedla powierzchnię weryfikowaną w 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->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Integration smoke test');

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

assert(str_starts_with($bytes, '%PDF'), 'Integration smoke test failed');
echo "Integration OK\n";

W kontekście Hypertext Transfer Protocol (HTTP) lub procesu roboczego użyj Output(..., 'F') lub 'S'. Nie polegaj na trybie inline. Pełne wskazówki dotyczące eksploatacji opisano w /integrations/tcpdf-compat/production-usage/.

Publiczne punkty wejścia API

Punkt wejścia	Przeznaczenie
`NextPDF\Compat\Tcpdf\TCPDF`	Fasada zgodna z TCPDF. Utwórz jedną na dokument.
`TCPDF::getDocument()`	Zwraca opakowany obiekt `NextPDF\Core\Document` — punkt przejścia do nowoczesnego API.
`TCPDF::setStrictMode(bool)`	Przełącznik audytu migracji (zobacz /integrations/tcpdf-compat/configuration/).
`NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()`	Opcjonalne globalne aliasy klas.
`NextPDF\Compat\Tcpdf\Config\AdaptationConfig`	Nowoczesny, niezmienny obiekt konfiguracji.
`NextPDF\Compat\Contracts\CompatAdapterInterface`	Współdzielony kontrakt zgodności.

Pokrycie API TCPDF

Miarodajna, zweryfikowana testami macierz pokrycia znajduje się w pliku docs/TCPDF_COVERAGE.md w repozytorium. Podsumowanie dla czytelnika — metody odwzorowane, cicho pomijane, niezaimplementowane oraz niemające zastosowania — znajduje się w /integrations/tcpdf-compat/method-coverage/. Nie nazywaj tego implementacją „drop-in replacement” ani „w 100% zgodną”. Opisuj to jako alternatywę zgodną z TCPDF o znanej, przetestowanej powierzchni i udokumentowanych różnicach w zachowaniu.

Zobacz też

docs/TCPDF_COVERAGE.md — miarodajne źródło pokrycia w repozytorium
/integrations/tcpdf-compat/boot-and-discovery/ — udostępnianie fasady i zachowanie aliasów
/integrations/tcpdf-compat/method-coverage/ — zachowanie poszczególnych metod i braki
/integrations/tcpdf-compat/migration/ — etapowa strategia migracji
/integrations/tcpdf-compat/production-usage/ — jak uruchamiać adapter pod obciążeniem
tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — źródło prawdy dla zachowania wyjścia