Pourquoi ton moteur PDF a sa place en PHP, pas dans un sidecar

Spec: ISO/IEC 25010:2023, §3.7Spec: ISO 32000-2, §7

En bref

Il y a deux endroits où un PDF peut être fabriqué : à l’intérieur de ton processus PHP, ou ailleurs, là où tu dois l’exploiter. NextPDF le fabrique à l’intérieur. Cette page est l’argument en faveur de ce choix — pourquoi un moteur en cours de processus est en général le bon réglage par défaut, et ce que le schéma de l’« ailleurs » coûte réellement une fois en production.

C’est l’angle de l’architecture, pas celui du framework. La façon dont le même moteur atteint Laravel, Symfony, CodeIgniter et le code autonome est une autre histoire, racontée dans one engine, every framework.

Pourquoi c’est important

Une fonctionnalité PDF démarre rarement comme un système que tu exploites. Elle démarre comme une ligne dans un contrôleur : rends cette facture, renvoie ce rapport. Le schéma sidecar transforme cette ligne en infrastructure. Pour dessiner le document, tu exécutes désormais une seconde chose — un binaire externe, un navigateur sans interface, un microservice séparé — et tout ce dont cette seconde chose a besoin devient ton problème aussi : sa version, sa mémoire, son conteneur, son réseau, ses modes de défaillance, sa page d’astreinte à 2 h du matin.

Le coût est invisible sur la démo et inévitable en production. Un moteur documentaire qui vit dans ton processus n’en a aucun. La question n’est pas « un sidecar peut-il fabriquer un PDF » — bien sûr qu’il le peut. C’est « qu’as-tu accepté d’exploiter pour y arriver, et en avais-tu besoin ».

La version courte

En cours de processus signifie pas de second environnement d’exécution. NextPDF dessine le PDF à l’intérieur du même worker PHP qui a traité la requête. Il n’y a pas de sous-processus à lancer, pas de service à déployer, et rien de plus à maintenir en vie.
Un sidecar ajoute une surface opérationnelle que tu n’avais pas. Un navigateur intégré ou un binaire externe apporte sa propre version, sa propre empreinte de sécurité, et son propre conteneur — que tu corriges et surveilles désormais.
Les frontières de processus sont là où les choses tournent mal. Démarrages à froid, expirations de délai, plomberie inter-processus fragile, et données quittant ton processus sont des modes de défaillance qu’un appel en cours de processus n’a tout simplement pas.
En cours de processus est testable et déterministe. Le moteur est du PHP typé que tu peux tester unitairement, simuler et raisonner — et non un moteur de rendu opaque que tu ne peux sonder qu’en l’exécutant et en regardant la sortie.
Un vrai navigateur a tout de même de vrais usages. Pour le rendu fidèle au pixel près de pages web modernes arbitraires, un navigateur sans interface est l’outil honnête — et NextPDF peut lui déléguer délibérément. C’est une jointure, pas le réglage par défaut.

Comment NextPDF l’aborde

Mets les deux architectures côte à côte. Le chemin en cours de processus est un appel de fonction. Le chemin sidecar est un système distribué en miniature — et chaque flèche entre ses boîtes est un endroit qui défaille indépendamment de ton code.

In-process: call the enginewriteHtml() or the document API runs inside the current PHP worker — no subprocess, no socket.
In-process: receive PDF bytesThe engine returns native PDF content directly; nothing left the process.
Sidecar: serialize and shipMarkup or a request is marshalled out of your process to a binary, browser, or remote service.
Sidecar: cross the boundaryA process spawn or network hop — with a cold start, a timeout, and an IPC contract that can break.
Sidecar: run a second runtimeAn external renderer with its own version, memory profile, and security surface to operate and patch.
Sidecar: deserialize backMarshal the result back in and translate the renderer’s errors into yours.

Le chemin en cours de processus face au chemin sidecar. En cours de processus, le PDF est produit par un appel typé à l'intérieur du même worker PHP et renvoyé directement. Le chemin sidecar ajoute une étape de sérialisation, une frontière de processus ou de réseau, un environnement d'exécution externe avec sa propre version et son empreinte, et une étape de désérialisation en retour — chacune un mode de défaillance distinct que l'appel en cours de processus n'a pas.

Pas de second environnement d’exécution à exploiter. Le schéma sidecar, ce sont deux systèmes portant le costume d’une seule fonctionnalité. Un wkhtmltopdf intégré, un service Chromium sans interface, un microservice de rendu séparé — chacun est un environnement d’exécution avec sa propre cadence de publication et ses propres bogues. Tu hérites de tout cela. Le moteur en cours de processus se livre comme une dépendance Composer ; il est mis à jour comme toute autre bibliothèque dans ton composer.json, sans aucun démon, image ou socket ajouté à ton déploiement.

Dérive de version et surface de sécurité plus large. Un navigateur intégré est une base de code vaste et à évolution rapide, avec un flux régulier d’avis de sécurité. Épingle-la et elle pourrit ; suis-la et elle s’agite. Dans les deux cas, c’est toute la plateforme web d’un moteur de rendu installée dans ta chaîne d’approvisionnement pour alimenter un seul document. Un moteur PHP en cours de processus est une bibliothèque ciblée de code que tu peux lire ; sa surface de sécurité est le PHP que tu exécutes déjà, et non une seconde plateforme que tu exécutes aussi désormais.

Les données restent à l’intérieur de la frontière de ton processus. Quand tu fais appel à l’extérieur, le contenu du document — qui est souvent exactement la donnée sensible qu’un PDF existe pour porter — franchit une frontière. Il est écrit dans un tube, un argument, un fichier temporaire, ou une socket réseau vers un service. Chacun de ceux-là est un endroit où fuiter, où journaliser par accident, ou où laisser une trace. En cours de processus, la donnée ne quitte jamais le worker qui la possède. Le rayon de souffle est un seul processus, pas une flotte.

Plomberie fragile, démarrages à froid et expirations de délai. Les appels inter-processus et réseau défaillent de façons qu’un appel de fonction ne peut pas : le sous-processus qui n’a pas démarré, la socket qui a bloqué, le délai d’expiration que tu as mal estimé, le démarrage à froid sous une pointe de trafic. Chacun nécessite une politique de réessai, un disjoncteur, et un budget. Un rendu en cours de processus renvoie soit des octets, soit une exception typée que tu attrapes à la ligne suivante. Il n’y a aucun état réseau partiel à réconcilier.

L’observabilité et le test deviennent plus difficiles au-delà de la frontière. Une défaillance dans un sidecar arrive sous la forme d’un code de sortie, d’une ligne de journal tronquée, ou d’un 500 d’un service que tu ne contrôles pas. La reproduire signifie reproduire tout cet environnement. Un moteur en cours de processus est observable avec les outils que tu utilises déjà — une trace d’appel, un débogueur, un profileur — et il est testable comme le reste de ton PHP. Cette testabilité est une propriété nommée de qualité logicielle : l’ISO/IEC 25010 la place sous la maintenabilité (Spec: ISO/IEC 25010:2023, §3.7), et une bibliothèque en cours de processus la satisfait bien plus directement qu’un moteur de rendu que tu ne peux exercer qu’en le lançant.

Le PDF sur lequel ces tests s’appuient est une structure définie, pas une boîte noire. Un fichier PDF a une disposition d’objets et de fichier spécifiée (Spec: ISO 32000-2, §7), et un moteur en cours de processus émet cette structure à partir de code que tu peux lire — si bien qu’un test golden ou structurel vérifie des octets qu’une fonction connue a produits, plutôt que la sortie d’un programme externe que tu ne peux qu’observer.

Exemple concret

Tout l’intérêt tient en une poignée de lignes. Il n’y a pas de client, pas d’URL de base, pas de vérification de santé, et pas de politique de réessai — parce qu’il n’y a pas de second système.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

// The engine runs inside this very process. No subprocess is spawned,
// no socket is opened, and the report data never leaves the worker.
$document = Document::createStandalone();
$document->setTitle('Quarterly Report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Quarterly Report</h1>
<p>Rendered <strong>in-process</strong> by PHP — no browser, no sidecar.</p>
HTML;

$document->writeHtml($html);

// PDF bytes are returned directly. There is no boundary to marshal across,
// so there is no timeout, cold start, or deserialization step to handle.
$bytes = $document->getPdfData();

Mets cela en regard de la forme de la version sidecar — non pas son code, sa forme opérationnelle. Elle nécessite qu’un binaire ou un service soit installé et joignable, une requête sérialisée et envoyée, un délai d’expiration choisi, un chemin de défaillance pour quand le moteur de rendu est froid ou en panne, et le résultat ramené par marshalling. Rien de tout cela n’est dans l’extrait ci-dessus, parce que rien de tout cela n’existe quand le moteur est une bibliothèque.

Idée fausse courante

L’hypothèse fréquente est qu’un « vrai » rendu PDF doit signifier un navigateur, donc le cours de processus doit être la version jouet. Cela inverse le compromis. Un navigateur est le bon outil quand tu as besoin d’un rendu exact, fidèle au pixel près, de contenu web moderne arbitraire. C’est le mauvais réglage par défaut pour le travail de forme documentaire que la plupart des équipes font réellement — factures, rapports, relevés, contrats — où la mise en page est connue, la donnée est la tienne, et la justesse est vérifiée par un validateur, non à l’œil. Pour ce travail, le poids opérationnel d’un sidecar ne t’apporte rien que le moteur en cours de processus ne te donne déjà, et te coûte tout ce qui figure dans les sections ci-dessus.

L’idée fausse en miroir est celle que cette page prend soin de ne pas commettre : prétendre qu’un moteur en cours de processus rend « tout le web » comme un navigateur. Ce n’est pas le cas, et NextPDF ne prétend pas que ce le soit. Son pipeline HTML en cours de processus est un sous-ensemble aligné sur la spécification, axé sur la mise en page documentaire, avec des frontières documentées — la portée honnête est exposée dans the HTML pipeline. Quand tu as vraiment besoin de la fidélité complète d’un navigateur, c’est une délégation délibérée et explicite, pas un repli silencieux.

Limites et frontières

En cours de processus est le bon réglage par défaut. Ce n’est pas une affirmation universelle selon laquelle un sous-processus n’est jamais justifié. Là où un document exige vraiment le rendu exact de CSS modernes arbitraires que le moteur en cours de processus ne couvre pas, déléguer à un navigateur sans interface est le bon choix — et NextPDF prend en charge ce chemin délibérément, avec son accès réseau restreint, comme une jointure plutôt que le réglage par défaut. Les deux ne sont pas rivaux ; ce sont des outils différents pour des travaux différents.

Cette page argumente l’architecture, pas une matrice de prise en charge CSS. Exactement quels HTML et CSS le pipeline en cours de processus couvre est défini par le code du moteur et ses tests de conformité, et est documenté avec ce pipeline — non promis ici. « En cours de processus » décrit le chemin de rendu par défaut ; ce n’est pas une affirmation selon laquelle chaque chemin possible évite un sous-processus.

La surface de capacité reste simple : le moteur en cours de processus est Core, et le chemin de délégation au navigateur est une extension optionnelle, indépendante de l’édition.

Where the PDF is rendered — edition availability
Edition	Availability
Core	Core renders PDF in-process in PHP — no subprocess, binary, or sidecar by default.
Pro	The headless-browser delegation path is an optional add-on extension, independent of edition tier.
Enterprise	The headless-browser delegation path is an optional add-on extension, independent of edition tier.

Documentation associée

The HTML pipeline — la portée honnête du moteur en cours de processus, et exactement quand déléguer à un navigateur est justifié.
One engine, every framework — l’axe complémentaire : comment le même moteur en cours de processus atteint chaque framework PHP sans une bibliothèque différente par pile.
Operating NextPDF in production — à quoi ressemble au quotidien l’exploitation d’un moteur en cours de processus, sans aucun environnement d’exécution supplémentaire à exploiter.
Memory and streaming — comment le moteur maintient la génération en cours de processus bornée sous charge.

Glossaire

Génération en cours de processus — produire le PDF à l’intérieur du même worker PHP qui traite la requête, sans sous-processus, socket ou service externe.
Sidecar — un environnement d’exécution séparé qui tourne aux côtés de ton application pour faire un seul travail ; ici, un binaire externe, un navigateur sans interface, ou un microservice qui rend le PDF en dehors de ton processus.
Démarrage à froid — la latence et le pic de ressources subis lorsqu’un sous-processus ou un service doit être démarré à partir de rien avant de pouvoir servir la première requête.
IPC — communication inter-processus : les tubes, sockets, fichiers temporaires, ou appels réseau utilisés pour passer des données vers et depuis un processus séparé, et une source récurrente de défaillances fragiles et difficiles à déboguer.
Jointure de délégation au navigateur — le chemin optionnel et explicite qui confie un rendu à un navigateur sans interface pour une fidélité exacte, avec l’accès réseau aux sous-ressources bloqué ; un choix délibéré, pas le réglage par défaut.