Receptariusz integracji

Rdzeń NextPDF renderuje Portable Document Format (PDF) 2.0 z poziomu PHP. Dziewięć pakietów integracyjnych łączy ten silnik z frameworkiem, zapleczem renderującym, starszym kodem, potokiem kompilacji lub usługą sieciową. Ta strona wyjaśnia przeznaczenie każdej integracji, podaje nazwę jej pakietu i ograniczenie wersji rdzenia (odczytane bezpośrednio z jej pliku composer.json) oraz odsyła do receptur poszczególnych integracji, które trafiają tutaj w miarę publikowania drzew docs/public/ przez repozytoria źródłowe.

Ta strona jest indeksem, więc nie zawiera żadnych deklaracji dotyczących zachowania poszczególnych integracji. Za receptury odpowiada repozytorium danej integracji. Agregator pobiera je do tej witryny. Dopóki receptura się nie pojawi, jej odnośnik wskazuje na obiekt zastępczy. Rekomendację opartą na przypadkach użycia znajdziesz w artykule Wybór integracji. Kontrakt, którego przestrzega każda uruchamialna receptura, opisuje artykuł Konwencje receptur.

Pięć kształtów integracji

Dziewięć pakietów dzieli się na pięć kształtów. Każdy z nich wskazuje, jaki rodzaj problemu rozwiązuje dana integracja.

Integracje frameworkowe wpinają NextPDF w kontener usług i cykl życia żądania frameworka aplikacji: nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter. Instalujesz jedną z nich, pobierasz usługę z kontenera i zwracasz odpowiedź PDF.
Mosty renderujące przekazują etap konwersji z HTML do PDF lub z Office do PDF do zewnętrznego zaplecza renderującego zamiast do potoku działającego w procesie: nextpdf/artisan (headless Chrome przez protokół Chrome DevTools Protocol), nextpdf/gotenberg (mikrousługa Gotenberg), nextpdf/cloudflare (Cloudflare Browser Rendering na brzegu sieci).
Warstwa zgodności umożliwia kodowi napisanemu dla starszej biblioteki PDF wywoływanie NextPDF, zanim ten kod zostanie przepisany: nextpdf/compat-legacy.
Narzędzie kompilacji tworzy backport NextPDF dla PHP 8.1 / 7.4 z przeznaczeniem dla środowisk uruchomieniowych, które nie mogą działać na wersji 8.4: nextpdf/backport-builder.
Usługa sieciowa udostępnia NextPDF przez Representational State Transfer (REST), gRPC oraz Model Context Protocol systemom AI i zdalnym wywołującym: nextpdf/server (dystrybuowana jako NextPDF Connect).

Mosty renderujące, które posługują się protokołem Hypertext Transfer Protocol (HTTP) (nextpdf/gotenberg, nextpdf/cloudflare oraz ścieżka klienta HTTP w nextpdf/laravel), wymagają klienta HTTP zgodnego z PHP Standard Recommendation 18 (PSR-18), dostarczanego przez aplikację hosta. Zgodnie z PSR-18 §4 klient zgłasza typowany wyjątek klienta tylko wtedy, gdy w ogóle nie może wysłać żądania. Na mocy tej samej klauzuli PSR-18 §4 odpowiedź HTTP 4xx lub 5xx jest zwykłą wartością zwracaną, a nie wyjątkiem. Receptury, które wywołują zdalny silnik renderujący, obsługują błędy transportu i statusy niepowodzenia jako odrębne przypadki.

Wykaz pakietów i ograniczeń rdzenia

Każda wartość poniżej pochodzi z pliku composer.json wskazanego pakietu (miarodajnego źródła). Ograniczenie rdzenia to zadeklarowany przez pakiet wymóg nextpdf/core. nextpdf/backport-builder nie deklaruje wymogu dotyczącego nextpdf/core, ponieważ przekształca kod źródłowy silnika, zamiast zależeć od niego w czasie wykonywania.

Integracja	Pakiet	Kształt	Ograniczenie rdzenia	Receptura
Laravel	`nextpdf/laravel`	framework	`^3.0 \|\| ^5.2`	Szybki start z Laravel [[/integrations/laravel/quickstart/]]
Symfony	`nextpdf/symfony`	framework	`^3.0 \|\| ^5.2`	Szybki start z Symfony [[/integrations/symfony/quickstart/]]
CodeIgniter 4	`nextpdf/codeigniter`	framework	`^3.0 \|\| ^5.2`	Szybki start z CodeIgniter [[/integrations/codeigniter/quickstart/]]
Artisan (Chrome)	`nextpdf/artisan`	Most renderujący	`^3.0 \|\| ^5.2`	Szybki start z Artisan [[/integrations/artisan/quickstart/]]
Gotenberg	`nextpdf/gotenberg`	Most renderujący	`^3.0`	Szybki start z Gotenberg [[/integrations/gotenberg/quickstart/]]
Cloudflare	`nextpdf/cloudflare`	Most renderujący	`^3.0`	Szybki start z Cloudflare [[/integrations/cloudflare/quickstart/]]
Zgodność (legacy)	`nextpdf/compat-legacy`	Warstwa zgodności	`^3.0`	Szybki start z Compat-legacy [[/integrations/compat-legacy/quickstart/]]
Kreator backportu	`nextpdf/backport-builder`	Narzędzie kompilacji	nie dotyczy	Szybki start z backportem [[/integrations/backport/quickstart/]]
Connect (serwer)	`nextpdf/server`	Usługa sieciowa	`^3.0`	Szybki start z Connect [[/integrations/connect/quickstart/]]

NextPDF dystrybuuje nextpdf/server pod nazwą produktu NextPDF Connect; receptury tego pakietu znajdują się pod identyfikatorem connect. nextpdf/compat-legacy pochodzi z rodziny compat; jego receptury znajdują się pod identyfikatorem compat-legacy.

Każdy pakiet we własnym środowisku uruchomieniowym wymaga PHP >=8.4 <9.0. nextpdf/backport-builder istnieje po to, aby tworzyć artefakty działające na PHP 8.1 (oraz na docelowej wersji 7.4). W starszym środowisku uruchomieniowym działa wynikowy silnik po backporcie, a nie sam kreator.

Do czego służy każda integracja

Integracje frameworkowe

nextpdf/laravel — dostawca usług dla Laravel 12, fasada oraz pomocnicze funkcje odpowiedzi PDF. Użyj go w aplikacji Laravel, gdy chcesz, aby NextPDF był pobierany z kontenera i zwracany jako odpowiedź HTTP bez ręcznego wpinania. Receptura: [[/integrations/laravel/quickstart/]].
nextpdf/symfony — pakiet (bundle) dla Symfony 7 z usługami wstrzykiwania zależności oraz pomocniczymi funkcjami odpowiedzi PDF. Użyj go w aplikacji Symfony. Pakiet rejestruje silnik jako usługę i integruje się z odpowiedziami symfony/http-foundation. Receptura: [[/integrations/symfony/quickstart/]].
nextpdf/codeigniter — usługa CodeIgniter 4, opakowanie biblioteki oraz pomocnicze funkcje odpowiedzi PDF. Użyj go w aplikacji CodeIgniter 4, gdy chcesz, aby NextPDF był dostępny przez lokalizator usług frameworka. Receptura: [[/integrations/codeigniter/quickstart/]].

Mosty renderujące

nextpdf/artisan — silnik renderujący oparty na headless Chrome przez protokół Chrome DevTools Protocol. Użyj go, gdy dokument wymaga przeglądarkowego silnika Cascading Style Sheets (CSS) dla wierności układu, której nie zapewnia potok HTML działający w procesie, a proces Chrome możesz uruchomić blisko aplikacji. Receptura: [[/integrations/artisan/quickstart/]].
nextpdf/gotenberg — konwersja z Office do PDF i z HTML do PDF przez mikrousługę Gotenberg. Użyj go, gdy wejściem jest dokument Office lub gdy renderowanie musi przebiegać poza procesem, w osobnej usłudze. Korzysta z HTTP za pośrednictwem klienta PSR-18 dostarczonego przez hosta. Receptura: [[/integrations/gotenberg/quickstart/]].
nextpdf/cloudflare — renderowanie bezserwerowe przez interfejs Cloudflare Browser Rendering API. Użyj go, gdy renderowanie powinno odbywać się na brzegu sieci bez utrzymywania długo żyjącego procesu przeglądarki. Korzysta z HTTP za pośrednictwem klienta PSR-18 dostarczonego przez hosta. Receptura: [[/integrations/cloudflare/quickstart/]].

Warstwa zgodności

nextpdf/compat-legacy — warstwa zgodności dla kodu napisanego pod starszą bibliotekę PDF. Użyj jej, aby wywoływać NextPDF z istniejącego kodu przed przepisaniem miejsc wywołań. To pomoc migracyjna, a nie trwała zależność. Receptura: [[/integrations/compat-legacy/quickstart/]].

Narzędzie kompilacji

nextpdf/backport-builder — potok obniżania wersji oparty na Rectorze, który tworzy build NextPDF dla PHP 8.1 (oraz docelowej wersji 7.4). Użyj go, gdy środowisko uruchomieniowe nie może przejść na PHP 8.4, a silnik jest tam nadal potrzebny. To infrastruktura kompilacji, a nie zależność czasu wykonywania aplikacji. Receptura: [[/integrations/backport/quickstart/]].

Usługa sieciowa

nextpdf/server (NextPDF Connect) — udostępnia NextPDF przez interfejs REST API, usługę gRPC oraz Model Context Protocol. Użyj go, gdy wywołujący są zdalni, używają innego języka lub są systemami AI, które potrzebują punktu końcowego narzędzia zamiast biblioteki PHP. Receptura: [[/integrations/connect/quickstart/]].

Jak rozwiązywane są odnośniki receptur

Każdy powyższy obiekt zastępczy [[…]] jest odwołaniem w przód do strony utworzonej w katalogu docs/public/ repozytorium integracji i pobranej do tej witryny przez agregator. Docelowe identyfikatory (slugi) stosują jedną konwencję:

/integrations/<integration>/<recipe>/

Token <integration> jest krótką nazwą zaczerpniętą bezpośrednio z powyższej tabeli wykazu pakietów i ograniczeń rdzenia. Każdy wiersz tej tabeli dostarcza jedną krótką nazwę. Pierwsza receptura publikowana przez każdą integrację nosi nazwę quickstart; późniejsze receptury używają dodatkowych segmentów <recipe> w obrębie tego samego korzenia <integration>. Dopóki strona docelowa nie zostanie zagregowana, jej odnośnik pozostaje obiektem zastępczym i nie jest rozwiązywany. Ten indeks nie zawiera żadnych deklaracji dotyczących zachowania stron docelowych. Zapisuje wyłącznie fakty dotyczące pakietów zweryfikowane na podstawie composer.json oraz identyfikator (slug), pod którym znajdą się receptury każdego repozytorium.

Zobacz także

Wybór integracji — macierz decyzyjna mapująca przypadki użycia na integracje.
Konwencje receptur — kontrakt, którego przestrzega każda uruchamialna receptura w tym receptariuszu.