Odejście od starszych bibliotek: TCPDF, FPDF i pokrewne

SpecSpec: ISO 32000-2ISO 32000-2SpecSpec: ISO 19005-4ISO 19005-4SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1

W skrócie

Jeśli Twoje pliki PDF generuje TCPDF, FPDF, mPDF lub dompdf, kod prawdopodobnie nadal działa. Właśnie dlatego kłopot łatwo przeoczyć. Biblioteka działa, plik się otwiera, a luka ujawnia się dopiero w dniu, w którym ktoś prosi o podpisany, archiwizowalny lub dostępny dokument, a odpowiedź brzmi „stąd się nie da”.

Ta strona to opowieść o migracji: czym są te ściany, dlaczego mają charakter strukturalny, a nie przypadkowy, oraz jak NextPDF daje Ci etapową drogę odejścia od nich — wraz z warstwą zgodności z TCPDF, która jest pomocą w migracji, a nie obietnicą identycznego co do bajta zamiennika.

Dlaczego to ma znaczenie

Biblioteka PDF to nie jednorazowe wywołanie renderujące. To zależność, którą Twoje dokumenty dziedziczą tak długo, jak długo istnieją. Gdy ta zależność przestaje się rozwijać, Twoje dokumenty tracą zdolność robienia nowych rzeczy — a dowiadujesz się o tym w najgorszym możliwym momencie, gdy klient, audytor lub regulator wyznacza poprzeczkę.

Te ściany wyglądają tak. Format poszedł naprzód: PDF 2.0 to obecne wydanie standardu (SpecSpec: ISO 32000-2ISO 32000-2), a moduł zapisujący utknięty na strukturze 1.x jest za formatem, który zakłada reszta Twojego łańcucha narzędzi. Podpisywanie jest szczątkowe lub doczepione, daleko poniżej profili bazowych PAdES, które sprawiają, że podpis się broni (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4). Wyjście archiwalne do rodziny PDF/A oraz struktura otagowana na potrzeby dostępności są albo nieobecne, albo kruche. A samo API jest nietypowane — orientacje jako ciągi znaków, pozycyjne wartości logiczne, wartości domyślne odkrywane przez przypadek — więc kompilator nie może Ci pomóc i recenzent również nie.

Żadne z tych nie są błędami, które da się obejść łatką. To kształt narzędzia zbudowanego dla wcześniejszej dekady, a kilka z tych narzędzi już aktywnie nie zmierza ku standardom, które Twoje dokumenty muszą teraz spełniać.

Wersja skrócona

• Starsze biblioteki PDF dla PHP w większości nadal działają. Problemem jest to, czego zazwyczaj nie potrafią wytworzyć z pełną nowoczesną zgodnością: PDF 2.0, podpisów zgodnych z profilem bazowym, zwalidowanego PDF/A, otagowanej dostępności — obsługa w wymienionych bibliotekach jest ograniczona lub jej brak.
• NextPDF to silnik dla PHP 8.4, który domyślnie zapisuje PDF 2.0, ze ścisłymi typami, profilami archiwalnymi i podpisywaniem PAdES jako pełnoprawnymi wynikami.
• Nie musisz przepisywać wszystkiego pierwszego dnia. Warstwa zgodności z TCPDF pozwala znanym wywołaniom dalej działać, gdy przenosisz logikę dokumentu, która ma znaczenie.
• Ta warstwa jest zgodna z TCPDF, ale nie identyczna co do bajta. To most przez migrację, z udokumentowanymi różnicami zachowania — a nie deklaracja, że każdy skrypt działa bez zmian.
• Uczciwym sprawdzianem jest to, czy nowe możliwości są warte ruchu. Dla niektórych obciążeń nie są i mówimy to wprost.

Jak podchodzi do tego NextPDF

Podejście polega na tym, by migracja była sekwencją, a nie skokiem. Przez cały czas wytwarzasz dokumenty i wymieniasz stare ograniczenia po kolei, zamiast stawiać całe wydanie na wielkim przepisaniu na raz.

1. InventoryCatalogue what your documents actually need to emit — signatures, archival profiles, tagged structure, fonts — not just which calls you make today.
2. BridgeAdopt the TCPDF-compatibility surface so the existing call sites keep producing files while the engine underneath becomes NextPDF.
3. PortMove the document logic that matters onto the native typed API, where intent is explicit and the compiler checks it.
4. UpgradeTurn on the outputs many legacy libraries cannot reach with full modern conformance: PDF 2.0 structure, validated PDF/A, PAdES signatures, tagged accessibility.
5. VerifyConfirm the result against a real validator, so 'archival' or 'signed' means a tool agrees, not just that the file opened.

Etapowa migracja ze starszej biblioteki PDF: zacznij od warstwy zgodności, aby istniejące wywołania dalej działały, następnie przenieś logikę dokumentu na typowane natywne API, a potem włącz wyjścia klasy standardowej (PDF 2.0, PDF/A, PAdES, dostępność), których wiele starszych bibliotek nie potrafi wytworzyć z pełną nowoczesną zgodnością.

PDF 2.0 jest punktem wyjścia, a nie flagą funkcji. NextPDF domyślnie zapisuje obecne wydanie formatu (SpecSpec: ISO 32000-2ISO 32000-2) i potrafi serializować starsze struktury, gdy zażąda ich profil. Biblioteka zamrożona na strukturze 1.x nie może Cię tu spotkać; to nie ustawienie, którego jej brakuje, to epoka, którą poprzedza.

Archiwalność i dostępność to właściwości modułu zapisującego. Wytworzenie pliku, który walidator akceptuje jako PDF/A, jest czymś, co silnik musi zrobić w trakcie zapisu — nie da się tego doczepić później (SpecSpec: ISO 19005-4ISO 19005-4). To samo dotyczy otagowanej struktury, która czyni PDF dostępnym. NextPDF buduje je podczas generowania, a to właśnie krok, którego wiele starszych narzędzi nie potrafi wykonać — albo wykonuje go tylko częściowo, poniżej tego, co akceptuje walidator.

Podpisywanie przekracza poprzeczkę profilu bazowego. Zaawansowane podpisy elektroniczne w PDF podążają za profilami PAdES (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4), gdzie skrót obejmuje zadeklarowany zakres bajtów, a podpis niesie metadane, które sprawdza walidator. Doczepiona pomoc do podpisywania rzadko sięga tej poprzeczki. NextPDF traktuje je jako pełnoprawne wyjście, a nie dodatek na końcu.

Warstwa zgodności jest mostem, postawionym uczciwie. Warstwa zgodności z TCPDF istnieje po to, by Twoje istniejące wywołania dalej wytwarzały dokumenty, gdy migrujesz części, które mają znaczenie. Podąża za tym samym modelem, co każdy przewodnik migracji NextPDF: zgodna z biblioteką źródłową, ale nie identyczna co do bajta, z zapisanymi różnicami zachowania. Ta uczciwość jest sednem — cicha deklaracja „99% zamiennika” to rodzaj zgadywania, który ten silnik ma odrzucać.

Human-factors note:Human-factors note

Powodem migracji rzadko jest kod, który masz dziś; jest nim dokument, o który poproszą Cię jutro. Łatwość utrzymania to nazwana właściwość jakości — jak gotowo system można analizować i zmieniać, gdy potrzeby się przesuwają (SpecSpec: ISO/IEC 25010, §3.6ISO/IEC 25010 §3.6). Zależność, która przestała się rozwijać, po cichu ją eroduje, a koszt czujesz dopiero wtedy, gdy pojawia się nowy wymóg, a odpowiedź musi brzmieć „stąd się nie da”. Etapowy ruch płaci ten koszt w Twoim harmonogramie, gdy dokumenty płyną dalej, zamiast naraz pod presją terminu.

Praktyczny przykład

Kształt migracji jest niewielki w miejscu wywołania. Stary kod dalej wytwarza plik przez warstwę zgodności; nowy kod wyraża intencję przez typowane natywne API i prosi o wyjście, którego starsza biblioteka nie potrafi osiągnąć albo osiąga tylko z ograniczoną zgodnością.

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use NextPDF\Contracts\Orientation;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

// 1) The bridge: a familiar TCPDF-shaped call keeps producing a file
//    while the engine underneath is already NextPDF. Behaviour is
//    compatible, not byte-identical — differences are documented.
$legacy = new TCPDF();
$legacy->AddPage();
$legacy->SetFont('helvetica', 'B', 16);
$legacy->Cell(0, 12, 'Migrated invoice', ln: 1);
$bridgedBytes = $legacy->Output('', 'S');

// 2) The destination: the same document expressed natively, where intent
//    is typed and the engine can emit what many legacy tools cannot.
$document = Document::createStandalone();
$document->setTitle('Migrated invoice');
$document->addPage(PageSize::a4(), Orientation::Portrait);
$document->setFont('helvetica', 'B', 16);
$document->cell(0, 12, 'Migrated invoice', newLine: true);

// Bytes only, no HTTP headers, no file side effect — stated, not inferred.
$nativeBytes = $document->output(dest: OutputDestination::String);

Pierwszy blok to punkt zaczepienia: nic w Twojej aplikacji nie musi się zmieniać, by dokumenty dalej płynęły. Drugi to cel: typowane wywołanie, w którym „portrait”, „string output” i czcionka są jawne, a archiwizacja, podpisywanie i dostępność stają się wyjściami, które możesz włączyć, a nie ścianami, na które wpadasz.

Częste nieporozumienie

Częstą nadzieją jest „musi być jakaś flaga, która sprawi, że moja stara biblioteka zrobi PDF 2.0 i podpisy”. Nie ma. To nie są opcje, które dojrzała biblioteka zapomniała udostępnić; to możliwości, wokół których jej architektura nigdy nie była zbudowana. Nie da się skonfigurować drogi do wydania formatu czy profilu podpisu, którego moduł zapisujący nie implementuje.

Lustrzane nieporozumienie głosi, że NextPDF to w 100% zamiennik TCPDF, więc migracja jest darmowa. Nie jest i nie będziemy udawać inaczej. Warstwa zgodności pokrywa realny, udokumentowany wycinek API, by przenieść Cię przez ruch; niektóre wywołania zachowują się inaczej, a kilka jest poza zakresem. Traktuj ją jak most z opublikowaną mapą, a nie gwarancję, że każdy starszy skrypt działa bez zmian.

Ograniczenia i granice

TCPDF-compatibility surface as a migration aid — edition availability

Edition	Availability
Core	○ Warstwa zgodności jest zgodna z TCPDF, ale nie identyczna co do bajta. Pokrywa udokumentowany podzbiór API, aby istniejące miejsca wywołań dalej wytwarzały pliki podczas migracji. To most, a nie zamiennik: niektóre zachowania się różnią, a niektóre wywołania nie są obsługiwane, wszystkie wymienione na stronach pokrycia metod i migracji. Celem jest natywne typowane API, gdzie mieszka wyjście klasy standardowej.
Pro	●Available
Enterprise	●Available

Migracja to środek, a nie cnota. Jeśli Twoje dokumenty są proste, Twoja biblioteka jest nadal utrzymywana, a nigdy nie będziesz potrzebować PDF 2.0, podpisywania, PDF/A ani dostępności, uczciwą odpowiedzią może być pozostanie tam, gdzie jesteś — koszt przesiadki jest realny, a ruch, którego nie potrzebujesz, to ruch, którego nie powinieneś robić. Strona o tym, kiedy nie używać NextPDF kreśli tę linię bez wahania.

Ta strona opisuje ścieżkę migracji i cele silnika. Dokładne pokrycie API, różnice zachowania oraz procedurę krok po kroku znajdziesz w dokumentacji zgodności, która jest źródłem prawdy o tym, co robi każde wywołanie. Nic tutaj nie obiecuje, że dowolny starszy skrypt zadziała bez zmian.

Powiązana dokumentacja

• Co zmieniło PDF 2.0 — wydanie formatu, którego wiele starszych bibliotek nie potrafi wyemitować, i dlaczego ma znaczenie.
• Warstwa zgodności z TCPDF — miarodajny przewodnik po tym, co pokrywa most i gdzie się różni.
• Kiedy nie używać NextPDF — uczciwa granica, dzięki której migrację, której nie potrzebujesz, możesz pominąć.
• Jeden silnik, każdy framework — gdzie silnik, na który migrujesz, wpina się w stos, który już prowadzisz.

Słowniczek

• PDF 2.0 — obecne wydanie standardu Portable Document Format (ISO 32000-2). Rozwinięte przy pierwszym użyciu; format, który NextPDF zapisuje domyślnie.
• PDF/A — rodzina zgodności archiwalnej (seria ISO 19005), która definiuje, co czyni PDF bezpiecznym do długotrwałego przechowywania. Właściwość, którą moduł zapisujący musi wytworzyć, a nie taka, którą wywołujący może dodać później.
• PAdES — PDF Advanced Electronic Signatures, rodzina profili ETSI (EN 319 142) do osadzania podpisów klasy standardowej w PDF. Rozwinięte przy pierwszym użyciu; omówione szczegółowo na stronach o podpisywaniu.
• Warstwa zgodności — warstwa API o kształcie biblioteki źródłowej (tu: TCPDF), która pozwala istniejącym miejscom wywołań dalej działać podczas migracji. Zgodna z oryginałem, ale nie identyczna co do bajta — most, a nie zamiennik.
• Zamiennik typu drop-in — substytut, który uruchamia istniejący kod bez zmian. Warstwa zgodności z TCPDF celowo nie jest tak opisywana; to udokumentowana pomoc w migracji ze znanymi różnicami zachowania.