Worker-sicherer Sitzungslebenszyklus mit NextPDF Connect

Auf einen Blick

Verwenden Sie in einem langlaufenden PHP-Worker (RoadRunner, Swoole, Laravel Octane) den richtigen Sitzungslebenszyklus. Jede Anfrage erstellt eine eigene Dokumentsitzung und baut sie nach output_pdf wieder ab. Kein Schriftart-, Seiten- oder Handle-Zustand sickert über die Anfragegrenze des Workers hinaus. Die Tools sind create_pdf, set_font, add_text und output_pdf — alle gehören zu Core.

Installation

composer require nextpdf/server

Binden Sie einen Transport ein. Das Muster funktioniert bei jedem Transport gleich.

Konzeptioneller Überblick

Eine document_id ist ein opakes Handle, das genau für eine Anfrage gültig ist. Die Regel lautet pro Anfrage erstellen, pro Anfrage abbauen, niemals zwischenspeichern oder teilen. Mit dem standardmäßigen destroy: true rendert output_pdf das Dokument und gibt die Sitzung in einem einzigen atomaren Schritt frei. Die nächste Anfrage auf demselben Worker erhält eine neue, unabhängige Sitzung. Schriftart und Inhalt der vorherigen Sitzung sind verschwunden. Jedes Tool-Ergebnis ist eine normale Transportantwort (PSR-18 §p2). Der Servercode selbst ist durch die Autoload-Grenze isoliert (PSR-4 §3). Der Sitzungsspeicher ist der einzige anfrageübergreifende Zustand und wird über die ID adressiert.

API-Oberfläche

Tool	Rolle	Risikostufe
`create_pdf`	Pro Anfrage eine Sitzung öffnen	Sicher
`set_font`	Die aktive Schriftart setzen (pro Sitzung)	Vorsicht
`add_text`	Inhalt schreiben	Vorsicht
`output_pdf`	Die Sitzung rendern und abbauen	Genehmigung erforderlich / Review (Base64)

Der Tool-Katalog ist maßgeblich. Welche Tools Ihnen zur Verfügung stehen, hängt von der installierten Edition ab.

Codebeispiel — Schnellstart

Anfrage 1: create_pdf → set_font → add_text → output_pdf (destroy: true). Anfrage 2 auf demselben Worker startet eine neue create_pdf-Sitzung. Die alte ID ist nun ungültig. Setzen Sie die Schriftart erneut, denn sie wird nicht übernommen.

Codebeispiel — Produktion

Kapseln Sie den Lebenszyklus so, dass die Bereinigung immer ausgeführt wird:

Erstellen Sie die Sitzung zu Beginn der Anfrage.
Bauen Sie den Inhalt auf.
Rufen Sie in einem zu finally äquivalenten Block output_pdf auf, damit die Sitzung abgebaut wird. Wenn Sie destroy: false für einen Ablauf mit Prüfung nach der Ausgabe verwendet haben, bauen Sie die Sitzung stattdessen explizit ab.

Speichern Sie eine document_id niemals in einer globalen Worker-Variablen, einer statischen Variablen oder einem geteilten Container. Geben Sie sie niemals zwischen Coroutinen, Fibers oder Anfrage-Handlern weiter.

Randfälle & Fallstricke

Wiederverwendete ID nach dem Abbau. Dies gibt einen Unknown-Document-Fehler zurück. Erstellen Sie pro Anfrage eine neue Sitzung.
Vergessenes output_pdf. Der Speicher wächst unbemerkt, bis die TTL der Sitzung abläuft oder der Prozess neu startet. Schließen Sie immer ab.
Sitzungslimit unter Last. Der Speicher begrenzt die Anzahl gleichzeitiger Sitzungen. Ein zügiger Abbau hält Sie darunter.
destroy: false ohne Bereinigung. Der Speicher wächst allmählich. Verwenden Sie es nur für einen expliziten Ablauf mit Prüfung nach der Ausgabe und bauen Sie die Sitzung danach ab.
Geteilte ID über gleichzeitige Anfragen hinweg. Das ist eine Race-Condition, die die Ausgabe beschädigt. Jede Anfrage besitzt ihre eigene Sitzung.

Performance

Pro Anfrage umfasst die Ausgabe nur wenige KB. Der Vorteil ist ein über die gesamte Lebensdauer des Workers begrenzter Speicherbedarf. Das Profil ist structural.

Sicherheitshinweise

Die Sitzungsisolation ist zugleich eine Vertraulichkeitseigenschaft. Der Inhalt einer Anfrage gelangt niemals in eine andere Anfrage, weil Handles nicht geteilt werden und die Sitzung bei der Ausgabe abgebaut wird.

Konformität

Aussage	Spezifikation	Klausel	reference_id
Jedes Tool-Ergebnis ist eine normale Transportantwort.	PSR-18	§p2
Der Code ist über die Autoload-Zuordnung von Klasse zu Datei isoliert.	PSR-4	§3

Kommerzieller Kontext

Nicht zutreffend — alle Tools sind Core.

Transportverfügbarkeit

Transport	Verfügbar	Hinweise
MCP (stdio)	Ja	Ein stdio-Prozess pro Worker ist üblich.
REST	Ja	Die HTTP-Anfragegrenze entspricht der Sitzungsgrenze.
gRPC	Ja	Eine Sitzung pro RPC-Sequenz.

HITL-Risikostufe

create_pdf hat die Stufe Sicher. set_font und add_text haben die Stufe Vorsicht. output_pdf hat die Stufe Genehmigung erforderlich und wird im Base64-Modus auf Review herabgestuft. In einem Worker ist die Base64-Ausgabe der übliche Weg und löst kein Gate aus (HITL-Risikostufen).

JSON-Umschlag des Bestätigungs-Gates

Base64-Worker-Ausgabe:

{ "allowed": true }