Przewodnik po decyzjach integracyjnych

Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x162 ISO/IEC/IEEE 26514:2022 §3.x162 Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 Evidence ¶ Editorial Evidence: Editorial

W skrócie

Ekosystem NextPDF składa się z niewielkiego rdzenia silnika oraz zestawu wyspecjalizowanych pakietów: mostków do frameworków, dwóch rendererów HTML, renderera edge i serwera wykonawczego. Ta strona przyporządkowuje rzeczywiste przypadki użycia do właściwych pakietów na podstawie tego, co faktycznie zawiera każdy z nich. Wybór pozostaje po stronie użytkownika i wynika z dowodów, a nie z sugestii dokumentacji.

Dlaczego to ma znaczenie

Wybór niewłaściwej integracji bywa kosztowny w sposób, który nie ujawnia się od razu. Jeśli wybierzesz zdalny renderer przeglądarkowy tam, gdzie silnik działający w procesie wyrenderowałby dokument poprawnie, do każdego pliku PDF dodasz wywołanie sieciowe oraz zależność od dostępności. Jeśli wybierzesz silnik działający w procesie dla dokumentu, który naprawdę wymaga pełnego przeglądarkowego silnika układu, otrzymasz plik z subtelnymi błędami. Wybrany pakiet kształtuje opóźnienia, tryby awarii i powierzchnię operacyjną, dlatego decyzja powinna być świadoma.

Wersja skrócona

• Zacznij od rdzenia silnika. Wszystko inne jest dodatkiem. Jeśli silnik działający w procesie renderuje dokument poprawnie, nie potrzebujesz żadnego pakietu renderera.
• Mostek frameworka wynika z używanego frameworka, a nie z dokumentu. Integracje z Laravel, Symfony i CodeIgniter istnieją po to, by udostępnić fasadę lub fabrykę, odpowiedź PDF, generowanie w kolejce i automatyczne wykrywanie — nie zmieniają tego, co silnik potrafi wyrenderować.
• Pakietu renderera używaj tylko wtedy, gdy wierność CSS wymaga przeglądarki. Artisan (lokalny Chrome) i Cloudflare (przeglądarka edge) istnieją właśnie po to; Gotenberg służy do wprowadzania dokumentów pakietu Office.
• Connect stosuj wtedy, gdy wywołującym jest usługa lub agent AI, a nie wywołanie PHP. Udostępnia silnik przez MCP, REST i gRPC z bramką potwierdzania przez człowieka dla niebezpiecznych operacji.

Jak NextPDF do tego podchodzi

Ekosystem jest celowo podzielony na warstwy, tak aby każdy pakiet miał jedno zadanie. Rdzeń silnika renderuje PDF w procesie. Mostek frameworka dostosowuje ten silnik do konwencji danego frameworka. Pakiet renderera deleguje układ HTML lub dokumentów Office do zewnętrznego silnika, gdy silnik działający w procesie nie jest właściwym narzędziem. Connect przekształca silnik w usługę sieciową. Żaden z tych pakietów nie wchodzi w zakres odpowiedzialności innego, dzięki czemu decyzja pozostaje możliwa do podjęcia. Nie wybierasz spośród konkurujących ze sobą narzędzi. Łączysz narzędzia, które się uzupełniają.

Podejmuj decyzję na podstawie przypadku użycia. Tabela przyporządkowuje każdy scenariusz do właściwego pakietu i wskazuje kompromis, na który się godzisz.

Przypadek użycia	Pasujący pakiet	Co faktycznie dostarcza	Kompromis, na który się godzisz
PDF w aplikacji Laravel	nextpdf/laravel	Automatycznie wykrywany dostawca usług, fasada Pdf, PdfResponse (inline/pobieranie/strumieniowanie, nagłówki OWASP), kolejkowane GeneratePdfJob z tries/timeout/backoff, rejestry blokad bezpieczne dla Octane	Zależność od Laravel 12; możliwości silnika pozostają bez zmian
PDF w aplikacji Symfony	nextpdf/symfony	Automatycznie rejestrowany bundle, wstrzykiwalny PdfFactory, PdfResponse oraz opcjonalny handler Messenger do generowania asynchronicznego	Zależność od bundle’a Symfony 7.2; możliwości pozostają bez zmian
PDF w aplikacji CodeIgniter 4	nextpdf/codeigniter	Helper service('pdf') / pdf(), biblioteka Pdf opakowująca jednorazowy Document, PdfResponse oraz opcjonalne zadanie kolejkowane	Zależność od CodeIgniter 4.6; możliwości pozostają bez zmian
Dokument wymaga pełnego przeglądarkowego CSS (flex/grid/czcionki webowe) w pobliżu procesu	nextpdf/artisan	Headless Chrome przez CDP, wyrenderowany, a następnie zaimportowany z powrotem jako Form XObject, aby tekst pozostał zaznaczalny; pula przeglądarek	Środowisko uruchomieniowe Chrome i jego koszt memory/process na hoście
Dokumenty pakietu Office (.docx, .xlsx) do PDF	nextpdf/gotenberg	Mostek PSR-18 do mikrousługi Gotenberg z transportem utwardzonym pod kątem SSRF i przypiętym do adresu IP	Zewnętrzna usługa Gotenberg i zależność sieciowa
HTML→PDF na brzegu sieci / bez lokalnego Chrome	nextpdf/cloudflare	Cloudflare Browser Rendering przez przypięty transport, z opcjonalnym przełączeniem awaryjnym na lokalny Chrome	Konto Cloudflare i zależność sieciowa; przełączenie awaryjne wymaga Artisan
Silnik wykorzystywany przez usługę lub agenta AI	nextpdf/server (Connect)	Jeden silnik przez MCP (stdio), REST (OpenAPI 3.1) i gRPC; wykrywanie narzędzi oparte na zależnościach miękkich; bramka potwierdzania przez człowieka dla narzędzi wysokiego ryzyka	Utrzymanie powierzchni usługowej; dyscyplina deterministycznego wykonywania

Human-factors note: Human-factors note

To dwie niezależne decyzje, które często są ze sobą łączone. O wyborze mostka frameworka decyduje framework, którego już używasz — nie rozszerza ani nie ogranicza tego, co silnik renderuje. O rendererze decyduje dokument. Pytaniem rozstrzygającym jest to, czy silnik CSS działający w procesie wystarcza, czy też dokument naprawdę wymaga przeglądarkowego silnika układu. Możesz potrzebować mostka frameworka bez renderera, renderera bez mostka, obu albo żadnego z nich. Traktowanie tych decyzji jako jednego pytania to najczęstszy błąd integracyjny, dlatego ta strona je rozdziela.

Co mówią dowody

Ta strona ma charakter redakcyjny — pomaga zdecydować, gdzie skierować użytkownika — ale to skierowanie opiera się na tym, co zawierają manifesty i główne klasy każdego pakietu.

Evidence ¶ Editorial Evidence: Editorial

Mostki istnieją i są zbudowane równolegle. Każdy z nich deklaruje zależność od frameworka oraz automatyczną rejestrację w swoim composer.json (extra.laravel.providers, extra.symfony.bundles, Registrar w CodeIgniter). Każdy dostarcza również PdfResponse, powiązanie jednorazowego dokumentu oraz opcjonalne zadanie kolejkowane. Żaden nie dodaje możliwości renderowania — wszystkie dostosowują ten sam silnik. Renderery także istnieją i są odrębne. Artisan zależy od chrome-php/chrome i importuje plik PDF z Chrome z powrotem jako Form XObject, aby tekst pozostał zaznaczalny. Gotenberg i Cloudflare to mostki HTTP PSR-18 z transportami jawnie utwardzonymi pod kątem SSRF i przypiętymi do adresu IP. Cloudflare może przełączyć się awaryjnie na Artisan, gdy Worker jest nieosiągalny. Plik composer.json Connect deklaruje trzy transporty oraz model zależności miękkich, w którym narzędzia pojawiają się w miarę instalowania ich pakietów; całość jest zarządzana czteropoziomowym modelem ryzyka z bramką potwierdzania przez człowieka.

Sposób, w jaki ta strona prowadzi czytelnika, jest pod względem formy poparty standardami: Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 mówi, że czytelnicy powinni być w stanie szybko ustalić, czy treść odpowiada ich celowi, a Spec Spec: ISO/IEC/IEEE 26514:2022, §3.x222 ISO/IEC/IEEE 26514:2022 §3.x222 wymaga, aby łącza i odwołania jasno wskazywały swój cel — dlatego tabela wskazuje konkretny pakiet i kompromis zamiast mglistego odwoływania się do „integracji”.

Praktyczny przykład

Decyzja jest sekwencją uczciwych pytań, a nie porównaniem funkcji. Poniższy przepływ rozstrzyga typowe przypadki.

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

Wniosek wynika z samej struktury: renderowanie i wywoływanie to odrębne osie. Odpowiadanie na oba pytania naraz sprawia, że zespoły kończą ze zdalnym rendererem, którego nie potrzebowały, albo z mostkiem, który nie rozwiązuje ich problemu z wiernością.

Częste nieporozumienie

Najczęstsze nieporozumienie brzmi: „Potrzebuję pakietu renderera, aby generować pliki PDF.” Tak nie jest. Rdzeń silnika generuje PDF w procesie. Pakiety rendererów istnieją wyłącznie dla konkretnego przypadku, w którym wymagany jest silnik układu klasy przeglądarki albo źródłem jest dokument pakietu Office. Gdy silnik działający w procesie już tworzy poprawny plik, odruchowe przyjęcie renderera dodaje zależność czasu działania i tryb awarii bez żadnej korzyści.

Drugie, lustrzane nieporozumienie brzmi: „mostek frameworka odblokowuje możliwości.” Tak nie jest. Mostek zmienia to, jak wywołujesz silnik — przez fasadę, fabrykę, odpowiedź lub zadanie kolejkowane — a nie to, co silnik potrafi wytworzyć. Podpisywanie, PDF/A i faktury strukturalne należą do kwestii poziomu i silnika, identycznych niezależnie od tego, czy wywołujesz go przez mostek, czy bezpośrednio.

Ograniczenia i granice

• Ta strona kieruje; nie testuje wydajności ani nie tworzy rankingu. Podaje, co dostarcza każdy pakiet oraz jaki kompromis się z tym wiąże. Wybór należy do użytkownika i powinien uwzględniać własne ograniczenia.
• Możliwości pakietów są odczytywane z ich manifestów i głównych klas w określonym momencie. Traktuj dokumentację każdego pakietu jako miarodajne źródło jego aktualnego API. Ten przewodnik jest mapą, a nie specyfikacją.
• Nie oferujemy ani nie sugerujemy żadnego porównania z konkurencją. Jedynym tematem jest ekosystem NextPDF i to, jak jego części do siebie pasują.
• Mostek frameworka i renderer to niezależne wybory. Mostek nie rozszerza możliwości silnika; renderer nie zależy od frameworka.
• Zewnętrzne renderery dodają zależność od dostępności. Gotenberg i Cloudflare wprowadzają wywołanie sieciowe oraz usługę, którą trzeba utrzymywać; to zaakceptowany kompromis, a nie ukryty koszt.
• Możliwości bramkowane poziomem są niezależne od integracji. Funkcje komercyjne odblokowuje poziom, a nie jakikolwiek mostek czy renderer; zobacz granicę poniżej.

Ecosystem packages and tiering — edition availability

Edition	Availability
Core	○ Każdy pakiet integracyjny (mostki, Artisan, Gotenberg, Cloudflare, Connect) działa z Core i jest na licencji Apache-2.0. Pakiety te dostosowują lub udostępniają silnik; nie bramkują funkcji.
Pro	○ Możliwości komercyjne (podpisywanie PAdES baseline, PDF/A, zaawansowane kody kreskowe) odblokowuje poziom i są one wtedy dostępne poprzez dowolną integrację, a nie dzięki zmianie integracji.
Enterprise	○ Faktury strukturalne, reguły walidacji oraz bramka potwierdzania przez człowieka w Connect dla narzędzi wysokiego ryzyka to możliwości danego poziomu, również niezależne od integracji.

Powiązane dokumenty

• Potok HTML — zakres silnika CSS działającego w procesie, który pozwala ustalić, kiedy renderer przeglądarkowy jest faktycznie potrzebny.
• Kiedy nie używać NextPDF — uczciwa granica problemów z dokumentami, dla których ten silnik nie jest właściwym narzędziem.
• Fundamenty PHP 8.4 — minimalne środowisko uruchomieniowe wspólne dla każdego pakietu oraz elementy zachowywane przez ścieżkę backportu.

Słowniczek

• Rdzeń silnika — nextpdf/core, działający w procesie silnik PDF 2.0, na którym opiera się każdy inny pakiet.
• Mostek frameworka — pakiet integracyjny (Laravel/Symfony/CodeIgniter), który dostosowuje silnik do konwencji frameworka, nie zmieniając jego możliwości.
• Pakiet renderera — pakiet, który deleguje układ HTML lub dokumentów Office do zewnętrznego silnika (Artisan/Cloudflare/Gotenberg), gdy silnik działający w procesie nie jest odpowiednim narzędziem.
• Form XObject — wielokrotnego użytku fragment treści PDF; Artisan importuje wyrenderowaną przez przeglądarkę stronę jako taki fragment, aby jej tekst pozostał zaznaczalny.
• NextPDF Connect — nextpdf/server, pakiet udostępniający silnik przez MCP, REST i gRPC z deterministyczną powierzchnią wykonawczą.
• Zależność miękka — model Connect, w którym narzędzia pojawiają się automatycznie w miarę instalowania opcjonalnych pakietów NextPDF, bez zmiany kodu.