Wygeneruj pierwszy plik PDF

W skrócie

Ten przepis pokazuje najkrótszą drogę od pustej sesji do wyrenderowanego pliku PDF przy użyciu NextPDF Connect. Tworzysz jednostronicowy dokument w formacie A4, dodajesz nagłówek i podtytuł, a następnie zwracasz plik jako base64. Całość opiera się na trzech narzędziach Core: create_pdf, add_text oraz output_pdf. Nie potrzebujesz czcionek, obrazów ani licencjonowanego poziomu.

Transport Connect wysyła każde wywołanie narzędzia jako żądanie i zwraca wynik narzędzia jako odpowiedź. Warstwa transportu jest niezależna od wyniku zwróconego przez narzędzie (PSR-18 §p2).

Instalacja

Zainstaluj NextPDF Server i podłącz transport:

composer require nextpdf/server

Uruchom serwer z transportem oczekiwanym przez hosta: Model Context Protocol przez stdio, REST lub gRPC. Zobacz Dostępność transportu poniżej. Narzędzia używane w tym przepisie należą do Core. Są dostarczane wraz z serwerem, więc nie potrzebujesz pakietu Pro ani Enterprise.

Omówienie koncepcyjne

Sesja Connect jest serwerowym magazynem dokumentów indeksowanym kluczem document_id. create_pdf otwiera sesję i zwraca identyfikator. Każde kolejne wywołanie narzędzia używa tego identyfikatora. Dokument zaczyna się od jednej pustej strony. Drzewo stron to struktura, za pomocą której czytnik dociera do każdej strony (ISO 32000-2 §7.7.3). output_pdf renderuje sesję do pliku PDF. Domyślnie po renderowaniu niszczy sesję, aby zwolnić pamięć.

Gdy wywołasz add_text bez jawnego x lub y, tekst zostaje rozmieszczony automatycznie. Zaczyna od bieżącej pozycji kursora, a po każdym wywołaniu kursor przesuwa się dalej.

Powierzchnia API

Podczas uruchamiania serwera te narzędzia są rozpoznawane przez rejestr narzędzi. Nazwy pokazane tutaj to nazwy protokołu z rejestru. Wiążącym źródłem jest scalony katalog narzędzi. Dostępne narzędzia zależą od zainstalowanego poziomu, ale te trzy są zawsze obecne w Core.

Narzędzie	Rola	Poziom ryzyka
`create_pdf`	Otwiera sesję dokumentu	Ostrożnie
`add_text`	Zapisuje tekst do dokumentu	Ostrożnie
`output_pdf`	Renderuje i zwraca plik PDF	Wymagane zatwierdzenie (tryb pliku) / Przegląd (base64)

Przykład kodu — szybki start

Host wykonuje kolejno trzy wywołania narzędzi:

Wywołaj create_pdf z page_size: "A4", orientation: "portrait" oraz tytułem i autorem dokumentu. Serwer zwraca document_id.
Wywołaj add_text z tym samym document_id, tekstem nagłówka, dużym font_size, width: 0 (pełna szerokość treści) oraz alignment: "center".
Wywołaj output_pdf z document_id. Bez file_path serwer zwraca plik PDF jako base64 i niszczy sesję.

Oto minimalny obiekt z argumentami create_pdf:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

Odpowiedź zawiera document_id, liczbę stron oraz geometrię strony. Traktuj identyfikator jako wartość nieprzezroczystą i nie wyprowadzaj z niego żadnego znaczenia.

Przykład kodu — produkcja

Wywołujący w środowisku produkcyjnym sprawdza każdą odpowiedź przed wykonaniem kolejnego wywołania. Nigdy nie używa ponownie document_id po tym, jak output_pdf zniszczył sesję.

create_pdf — potwierdź, że odpowiedź zawiera document_id. Jeśli serwer zwróci błąd limitu sesji, zwolnij nieużywane sesje i spróbuj ponownie.
add_text (nagłówek) — potwierdź, że odpowiedź zawiera position.
add_text (podtytuł) — użyj mniejszego font_size; kursor kontynuuje od miejsca poniżej nagłówka.
output_pdf — odczytaj pole base64 i zdekoduj je do bajtów. Flaga destroyed potwierdza, że sesja przestała istnieć.

Plik jest zwracany w treści odpowiedzi (tryb base64), więc nie powstaje żaden efekt uboczny w systemie plików ani nie uruchamia się bramka zatwierdzenia przez człowieka. Zobacz Poziom ryzyka HITL.

Przypadki brzegowe i pułapki

Zniszczona sesja. Po uruchomieniu output_pdf z domyślnym destroy: true document_id przestaje być prawidłowy. Każde późniejsze wywołanie, które go używa, zwraca błąd nieznanego dokumentu. Zamiast tego utwórz nową sesję.
Nieznany rozmiar strony. Serwer odrzuca page_size, którego nie rozpoznaje, i zwraca zrozumiały błąd. Użyj udokumentowanego rozmiaru (A3, A4, A5, A6, Letter, Legal, Tabloid).
Pusty tekst. Pusty text tworzy wpis o zerowej szerokości, a nie błąd. Sprawdź dane wejściowe przed wywołaniem.
Limit sesji. Magazyn w pamięci ogranicza liczbę sesji działających jednocześnie. Zwalniaj sesje niezwłocznie za pomocą output_pdf.

Wydajność

Pojedyncza strona zawierająca wyłącznie tekst renderuje się z dużym zapasem w ramach budżetu strony, a wynik ma zwykle 1–3 KB. Ten przepis używa profilu powtarzalności structural dla podwójnego renderowania. Plik PDF zawiera w trailerze /ID oraz znaczniki czasu, które zmieniają się przy każdym uruchomieniu, więc miarodajne jest porównanie strukturalne (znormalizowane).

Uwagi dotyczące bezpieczeństwa

Tryb base64 nie powoduje żadnego efektu ubocznego w systemie plików. Tryb zapisu do pliku taki efekt powoduje i jest objęty bramką. Zobacz sekcję HITL. Traktuj zwrócone base64 jako treść dokumentu, a nie jako zaufany kanał. Są to dokładnie te bajty, które wytworzyły narzędzia.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula
Transport wysyła żądanie i odbiera odpowiedź niezależnie od wyniku.	PSR-18	§p2
Dostęp do stron uzyskuje się poprzez drzewo stron dokumentu.	ISO 32000-2	§7.7.3

Ten przepis opisuje, jak serwer generuje dane wyjściowe. Nie deklaruje zgodności z profilem.

Kontekst komercyjny

Nie dotyczy — wszystkie trzy narzędzia należą do Core.

Dostępność transportu

Transport	Dostępny	Uwagi
MCP (stdio)	Tak	Wywołania narzędzi są mapowane na MCP `tools/call`.
REST	Tak	Każde narzędzie jest operacją REST; wynikiem jest treść odpowiedzi.
gRPC	Tak	Każde narzędzie jest wywołaniem jednoargumentowym.

Wynik narzędzia jest taki sam dla wszystkich transportów; różni się jedynie ramkowanie. Wynik niepomyślny nadal jest zwykłą odpowiedzią, a nie awarią transportu (PSR-18 §p2).

Poziom ryzyka HITL

Serwer umieszcza każde wywołanie narzędzia na skali ryzyka z udziałem człowieka (HITL): Bezpieczne (0) → Ostrożnie (1) → Przegląd (2) → Wymagane zatwierdzenie (3). create_pdf ma poziom Ostrożnie, a add_text poziom Ostrożnie. output_pdf wymaga zatwierdzenia, ale w trybie base64 (bez file_path) spada do poziomu Przegląd i działa bez potwierdzenia przez człowieka. W przypadku zapisu do pliku pozostaje na poziomie Wymagane zatwierdzenie. Zobacz output-approval oraz dokumentację poziomów ryzyka HITL.

Koperta JSON bramki potwierdzenia

Ten przepis pozostaje w trybie base64, więc bramka potwierdzenia zwraca kopertę zezwolenia:

{ "allowed": true }

Koperta wyzwania (allowed: false, z ciągiem challenge oraz jednorazowym token) jest udokumentowana w output-approval.