Cycle de vie worker-safe des sessions avec NextPDF Connect

En bref

Applique le bon cycle de vie de session dans un worker PHP de longue durée (RoadRunner, Swoole, Laravel Octane). Chaque requête crée sa propre session de document et la détruit après output_pdf. Aucun état de police, de page ou de handle ne franchit la frontière de requête du worker. Les outils concernés sont create_pdf, set_font, add_text et output_pdf, tous Core.

Installation

composer require nextpdf/server

Configure un transport. Ce motif fonctionne de la même manière avec n’importe quel transport.

Vue d’ensemble conceptuelle

Un document_id est un handle opaque dont la portée est limitée à une seule requête. La règle est : créer par requête, détruire par requête, ne jamais mettre en cache ni partager. Avec la valeur par défaut destroy: true, output_pdf effectue le rendu du document et libère la session en une seule étape atomique. La requête suivante sur le même worker obtient une session neuve et indépendante. La police et le contenu de la session précédente ont disparu. Chaque résultat d’outil est une réponse de transport normale (PSR-18 §p2). Le code du serveur lui-même est isolé par la frontière d’autoload (PSR-4 §3). Le magasin de sessions est le seul état partagé entre les requêtes, et il est indexé par id.

Surface d’API

Outil	Rôle	Niveau de risque
`create_pdf`	Ouvrir une session par requête	Sûr
`set_font`	Définir la police active (par session)	Attention
`add_text`	Écrire le contenu	Attention
`output_pdf`	Effectuer le rendu et détruire la session	Approbation requise / Revue (base64)

Le catalogue d’outils fait foi. Les outils disponibles dépendent de l’édition installée.

Exemple de code — Démarrage rapide

Requête 1 : create_pdf → set_font → add_text → output_pdf (destroy: true). La requête 2 exécutée sur le même worker démarre une toute nouvelle session create_pdf. L’ancien id est désormais invalide. Redéfinis la police, car elle n’est pas conservée.

Exemple de code — Production

Encapsule le cycle de vie afin que le nettoyage s’exécute toujours :

Obtiens la session au début de la requête.
Construis le contenu.
Dans un bloc équivalent à finally, appelle output_pdf, qui détruit la session. Si tu as utilisé destroy: false pour un flux d’inspection après sortie, détruis plutôt la session explicitement.

Ne stocke jamais un document_id dans une variable globale de worker, une variable statique ou un conteneur partagé. Ne le transmets jamais entre coroutines, fibers ou gestionnaires de requêtes.

Cas limites & pièges

Id réutilisé après destruction. Cela renvoie une erreur de document inconnu. Crée une nouvelle session par requête.
output_pdf oublié. La mémoire augmente silencieusement jusqu’à l’expiration du TTL de la session ou au redémarrage du processus. Finalise toujours.
Limite de sessions sous charge. Le magasin a un plafond de concurrence. Une destruction rapide te maintient sous ce plafond.
destroy: false sans nettoyage. La mémoire augmente progressivement. Ne l’utilise que pour un flux explicite d’inspection après sortie, puis détruis la session.
Id partagé entre requêtes concurrentes. Cela crée une situation de concurrence qui corrompt la sortie. Chaque requête possède sa propre session.

Performance

La sortie par requête représente quelques Ko. En contrepartie, la mémoire du worker reste bornée pendant toute sa durée de vie. Le profil est structural.

Notes de sécurité

L’isolation des sessions est aussi une propriété de confidentialité. Le contenu d’une requête n’est jamais visible par une autre, car les handles ne sont pas partagés et la session est détruite à la sortie.

Conformité

Énoncé	Spécification	Clause	reference_id
Chaque résultat d’outil est une réponse de transport normale.	PSR-18	§p2
Le code est isolé par le mappage classe-vers-fichier de l’autoload.	PSR-4	§3

Contexte commercial

Sans objet : tous les outils sont Core.

Disponibilité des transports

Transport	Disponible	Notes
MCP (stdio)	Oui	Un processus stdio par worker est la norme.
REST	Oui	La frontière de requête HTTP correspond à la frontière de session.
gRPC	Oui	Une session par séquence RPC.

Niveau de risque HITL

create_pdf est Sûr. set_font et add_text sont Attention. output_pdf est Approbation requise, et rétrogradé à Revue en mode base64. Dans un worker, la sortie base64 est le chemin courant et ne déclenche aucune validation (niveaux de risque HITL).

Enveloppe JSON de la validation de confirmation

Sortie base64 du worker :

{ "allowed": true }