Guide de décision pour l'intégration

Spec: ISO/IEC/IEEE 26514:2022, §3.x162 Spec: ISO 24495-1:2023, §5 Evidence: Editorial

En un coup d’œil

L’écosystème NextPDF s’articule autour d’un petit moteur core et d’un ensemble de packages ciblés — bridges de framework, deux moteurs de rendu HTML, moteur de rendu en périphérie et serveur d’exécution. Cette page met en correspondance des cas d’usage réels avec le package adapté, d’après ce que chaque package contient réellement. Le choix reste une décision que tu prends sur la base d’éléments vérifiables, au lieu d’être imposé par cette documentation.

Pourquoi c’est important

Choisir la mauvaise intégration a un coût qui ne se voit pas toujours immédiatement. Choisis un moteur de rendu navigateur distant alors que le moteur en cours de processus aurait rendu le document correctement, et tu ajoutes un aller-retour réseau ainsi qu’une dépendance de disponibilité à chaque PDF. Choisis le moteur en cours de processus pour un document qui a réellement besoin d’un moteur de mise en page de navigateur complet, et tu obtiens un fichier incorrect de façon subtile. Le package que tu adoptes façonne ta latence, tes modes de défaillance et ta surface opérationnelle ; la décision mérite donc d’être explicite.

La version courte

Commence par le moteur core. Tout le reste s’ajoute par-dessus. Si le moteur en cours de processus rend ton document correctement, tu n’as besoin d’aucun package de moteur de rendu.
Le bridge de framework suit ton framework, pas ton document. Les intégrations Laravel, Symfony et CodeIgniter existent pour te fournir une facade ou une factory, une réponse PDF, de la génération en file d’attente et l’auto-découverte — elles ne changent pas les capacités de rendu du moteur.
N’utilise un moteur de rendu que lorsque la fidélité CSS exige un navigateur. Artisan (Chrome local) et Cloudflare (navigateur en périphérie) existent exactement pour cela ; Gotenberg existe pour intégrer les documents Office.
Utilise Connect quand l’appelant est un service ou un agent IA, pas un appel PHP. Il expose le moteur via MCP, REST et gRPC avec un gate d’approbation humaine pour les opérations dangereuses.

Comment NextPDF aborde la question

L’écosystème est délibérément structuré en couches pour que chaque package ait un seul rôle. Le moteur core rend le PDF en cours de processus. Un bridge de framework adapte ce moteur aux idiomes d’un framework. Un package de moteur de rendu délègue la mise en page HTML ou Office à un moteur externe lorsque le moteur en cours de processus n’est pas l’outil adapté. Connect transforme le moteur en service réseau. Aucun de ces packages n’empiète sur la responsabilité d’un autre, ce qui rend la décision facile à raisonner. Tu ne choisis pas entre des outils concurrents ; tu composes des outils complémentaires.

La décision se prend d’abord à partir du cas d’usage. Le tableau associe chaque scénario au package adapté et explicite le compromis que tu acceptes.

Cas d’usage	Package qui convient	Ce qu’il fournit réellement	Le compromis que tu acceptes
PDF dans une application Laravel	`nextpdf/laravel`	Service provider avec auto-découverte, facade `Pdf`, `PdfResponse` (inline/téléchargement/streamé, en-têtes OWASP), un job `GeneratePdfJob` mis en file d’attente avec tries/timeout/backoff, des registres verrouillés et compatibles Octane	Une dépendance Laravel 12 ; les capacités du moteur sont inchangées
PDF dans une application Symfony	`nextpdf/symfony`	Bundle auto-enregistré, `PdfFactory` injectable, `PdfResponse`, un handler Messenger optionnel pour la génération asynchrone	Une dépendance de bundle Symfony 7.2 ; capacités inchangées
PDF dans une application CodeIgniter 4	`nextpdf/codeigniter`	Le helper `service('pdf')` / `pdf()`, une bibliothèque `Pdf` qui encapsule un `Document` jetable, un `PdfResponse`, un job mis en file d’attente optionnel	Une dépendance CodeIgniter 4.6 ; capacités inchangées
Le document a besoin du CSS complet d’un navigateur (flex/grid/polices web) à proximité du processus	`nextpdf/artisan`	Chrome headless via CDP, rendu puis réimporté comme Form XObject pour que le texte reste sélectionnable ; un pool de navigateurs	Un runtime Chrome et son coût memory/process sur ton hôte
Documents Office (`.docx`, `.xlsx`) vers PDF	`nextpdf/gotenberg`	Un bridge PSR-18 vers un microservice Gotenberg avec un transport durci contre la SSRF et épinglé par IP	Un service Gotenberg externe et une dépendance réseau
HTML→PDF en périphérie / pas de Chrome local	`nextpdf/cloudflare`	Cloudflare Browser Rendering via transport épinglé, avec un repli optionnel sur Chrome local	Un compte Cloudflare et une dépendance réseau ; le repli requiert Artisan
Moteur consommé par un service ou un agent IA	`nextpdf/server` (Connect)	Un seul moteur via MCP (stdio), REST (OpenAPI 3.1) et gRPC ; découverte d’outils par dépendance souple ; un gate de confirmation humaine pour les outils à haut risque	L’exploitation d’une surface de service ; une discipline d’exécution déterministe

Ce que disent les preuves

Cette page est éditoriale — elle oriente une décision de routage — mais ce routage s’appuie sur ce que le manifeste et les classes principales de chaque package contiennent réellement.

Les bridges existent réellement et suivent le même modèle. Chacun déclare sa dépendance de framework et son auto-enregistrement dans son composer.json (extra.laravel.providers, extra.symfony.bundles, le Registrar de CodeIgniter). Chacun embarque aussi un PdfResponse, un binding de document jetable et un job mis en file d’attente optionnel. Aucun d’eux n’ajoute de capacité de rendu — ils adaptent le même moteur. Les moteurs de rendu existent eux aussi et restent distincts. Artisan dépend de chrome-php/chrome et réimporte le PDF Chrome comme Form XObject pour garder le texte sélectionnable. Gotenberg et Cloudflare sont des bridges HTTP PSR-18 avec des transports explicitement durcis contre la SSRF et épinglés par IP. Cloudflare peut se replier sur Artisan quand le Worker est injoignable. Le composer.json de Connect déclare les trois transports et un modèle de dépendance souple dans lequel les outils apparaissent à mesure que leurs packages sont installés, gouverné par un modèle de risque à quatre niveaux assorti d’un gate de confirmation humaine.

Dans sa forme, l’orientation proposée par cette page est adossée à des normes : Spec: ISO 24495-1:2023, §5 indique que les lecteurs devraient pouvoir déterminer rapidement si le contenu sert leur objectif (chunk), et Spec: ISO/IEC/IEEE 26514:2022, §3.x222 exige que les liens et références indiquent leur destination — c’est pourquoi le tableau nomme le package concret et le compromis plutôt que de renvoyer vaguement à « une intégration ».

Exemple pratique

La décision est une suite de questions franches, pas une comparaison de fonctionnalités. La séquence suivante couvre les cas courants.

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

La leçon tient dans la structure : le rendu et l’invocation sont des axes distincts. Les traiter ensemble, c’est comme cela que des équipes se retrouvent avec un moteur de rendu distant dont elles n’avaient pas besoin ou avec un bridge qui ne résout pas leur problème de fidélité.

Idée fausse répandue

L’idée fausse dominante est « J’ai besoin d’un package de moteur de rendu pour générer des PDF. » Non. Le moteur core génère le PDF en cours de processus. Les packages de moteur de rendu n’existent que dans le cas précis où un moteur de mise en page de qualité navigateur est requis ou lorsque la source est un document Office. Lorsque le moteur en cours de processus produit déjà le bon fichier, adopter un moteur de rendu par réflexe ajoute une dépendance d’exécution et un mode de défaillance sans aucun bénéfice.

L’idée fausse symétrique est « le bridge de framework débloque des capacités. » Non. Un bridge change la manière dont tu appelles le moteur — facade, factory, réponse, job mis en file d’attente — pas ce qu’il peut produire. La signature, le PDF/A et les factures structurées relèvent du niveau et du moteur ; elles restent identiques que tu passes par un bridge ou en direct.

Limites et frontières

Cette page oriente ; elle ne fait ni benchmark ni classement. Elle énonce ce que chaque package fournit et le compromis associé. Le choix entre eux t’appartient, en fonction de tes contraintes.
Les capacités des packages sont lues depuis leurs manifestes et classes principales à un instant donné. Considère la documentation propre à chaque package comme la référence qui fait autorité pour son API actuelle. Ce guide est la carte, pas la spécification.
Aucune comparaison avec des concurrents n’est proposée ni sous-entendue. Le seul sujet est l’écosystème NextPDF et la façon dont ses parties s’articulent.
Le bridge de framework et le moteur de rendu sont des choix indépendants. Un bridge n’étend pas la capacité du moteur ; un moteur de rendu ne dépend pas d’un framework.
Les moteurs de rendu externes ajoutent une dépendance de disponibilité. Gotenberg et Cloudflare introduisent un appel réseau et un service à exploiter ; c’est le compromis accepté, pas un coût caché.
Les capacités liées au niveau sont orthogonales à l’intégration. Les fonctionnalités commerciales sont débloquées par le niveau, pas par un bridge ou un moteur de rendu ; voir la frontière ci-dessous.

Ecosystem packages and tiering — edition availability
Edition	Availability
Core	Chaque package d’intégration (bridges, Artisan, Gotenberg, Cloudflare, Connect) fonctionne avec Core et est sous licence Apache-2.0. Ils adaptent ou exposent le moteur ; ils ne verrouillent pas de fonctionnalités.
Pro	Les capacités commerciales (signature baseline PAdES, PDF/A, codes-barres avancés) sont débloquées par le niveau et deviennent alors disponibles à travers chaque intégration, pas en changeant d’intégration.
Enterprise	Les factures structurées, les politiques de validation et le gate de confirmation humaine de Connect pour les outils à haut risque sont des capacités de niveau, elles aussi indépendantes de l’intégration.

Documentation associée

Le pipeline HTML — ce que couvre le moteur CSS en cours de processus, pour que tu saches quand un moteur de rendu navigateur devient réellement nécessaire.
Quand ne pas utiliser NextPDF — la frontière honnête pour les problèmes de document sur lesquels le moteur n’est pas le bon outil.
Les fondations PHP 8.4 — le socle d’exécution que partage chaque package et ce que le chemin de backport préserve.

Glossaire

Moteur core — nextpdf/core, le moteur PDF 2.0 en cours de processus sur lequel s’appuient tous les autres packages.
Bridge de framework — un package d’intégration (Laravel/Symfony/CodeIgniter) qui adapte le moteur aux idiomes d’un framework sans changer ses capacités.
Package de moteur de rendu — un package qui délègue la mise en page HTML ou Office à un moteur externe (Artisan/Cloudflare/Gotenberg) lorsque le moteur en cours de processus n’est pas l’outil adapté.
Form XObject — un fragment de contenu PDF réutilisable ; Artisan importe une page rendue par le navigateur sous cette forme pour que son texte reste sélectionnable.
NextPDF Connect — nextpdf/server, le package exposant le moteur via MCP, REST et gRPC avec une surface d’exécution déterministe.
Dépendance souple — le modèle de Connect dans lequel les outils apparaissent automatiquement à mesure que des packages NextPDF optionnels sont installés, sans changement de code.