Choisir une intégration

Choisir une intégration

Cette page associe chaque cas d’usage à l’intégration qui le prend en charge. Chaque recommandation est tirée uniquement de la description du composer.json du package et de son objectif déclaré, tous deux lus directement depuis le dépôt source. Lorsque deux intégrations se recoupent, cette page indique le facteur qui les distingue et te laisse décider.

Trouve la ligne qui correspond à ta situation, puis pars de là.

Commence ici : qu’as-tu en main ?

Tu as …	Utilise	Pourquoi (objectif vérifié)
Une application Laravel 12	nextpdf/laravel	Intégration au framework Laravel : service provider, façade, helpers de réponse PDF.
Une application Symfony 7	nextpdf/symfony	Bundle Symfony : services d’injection de dépendances et helpers de réponse PDF.
Une application CodeIgniter 4	nextpdf/codeigniter	Services CodeIgniter 4, wrapper de bibliothèque et helpers de réponse PDF.
Une application PHP sans framework	nextpdf/core directement	Aucune intégration de framework n’est nécessaire ; le moteur est une simple bibliothèque.
Du HTML qui a besoin d’un moteur CSS de navigateur, et tu peux exécuter Chrome	nextpdf/artisan	Renderer Chrome CDP pour le HTML qui exige une mise en page CSS de qualité navigateur.
Un document Office à convertir, comme DOCX, XLSX ou ODT	nextpdf/gotenberg	Conversion Office vers PDF via un microservice Gotenberg.
Un besoin de rendu sans aucun processus de navigateur à gérer	nextpdf/cloudflare	Rendu serverless via la Cloudflare Browser Rendering API, à la périphérie du réseau.
Du code écrit pour une bibliothèque PDF historique	nextpdf/compat-legacy	Couche de compatibilité pour une bibliothèque PDF historique ; appelle NextPDF sans réécrire les sites d’appel.
Un runtime bloqué sur PHP 8.1 / 7.4	nextpdf/backport-builder	Pipeline de downgrade Rector qui construit une cible 8.1 / 7.4 du moteur.
Des appelants distants, un autre langage ou un système d’IA	nextpdf/server	NextPDF Connect : surface REST, gRPC et Model Context Protocol pour l’exécution à distance.

Quand deux intégrations peuvent convenir

Rendre du HTML en PDF : Artisan vs Gotenberg vs Cloudflare vs cœur

Les trois ponts de rendu transforment du balisage en PDF. Ils se distinguent par leur mode de fonctionnement, pas par leur qualité ; cette différence opérationnelle est donc le critère décisif.

• nextpdf/artisan pilote Chrome en mode headless via le Chrome DevTools Protocol. Il lui faut un processus Chrome joignable depuis l’application. Choisis-le quand tu peux gérer ce processus et que le document exige un moteur CSS de navigateur.
• nextpdf/gotenberg appelle un microservice Gotenberg hors processus via HTTP. Choisis-le quand le rendu doit être isolé dans son propre service, ou quand l’entrée est un document Office. Gotenberg est le seul des trois dont l’objectif déclaré inclut la conversion Office vers PDF.
• nextpdf/cloudflare appelle la Cloudflare Browser Rendering API. Choisis-le quand tu veux un rendu edge/serverless sans aucun processus de navigateur à exécuter ni à patcher.
• Le pipeline HTML in-process du cœur de NextPDF n’a besoin d’aucun des éléments ci-dessus. N’utilise un pont de rendu que lorsque le pipeline in-process ne peut pas atteindre la fidélité de mise en page ou l’isolation de processus dont le document a besoin. Un pont est un choix délibéré de déléguer cette étape, pas le chemin par défaut.

Les deux ponts HTTP (nextpdf/gotenberg, nextpdf/cloudflare) ont besoin d’un client HTTP PSR-18 fourni par l’hôte. Leurs recipes distinguent un échec de transport d’un statut HTTP qui n’indique pas une réussite.

Convertir un document Office

nextpdf/gotenberg est l’intégration dont la description vérifiée du composer.json mentionne la conversion Office vers PDF. Les autres ponts de rendu décrivent un rendu HTML, pas une entrée Office. Si la source est en DOCX/XLSX/ODT, c’est ton intégration.

Migrer depuis une bibliothèque PDF historique

D’après son objectif déclaré, nextpdf/compat-legacy est une couche de compatibilité pour les bases de code écrites pour une bibliothèque PDF historique. Elle permet aux sites d’appel existants d’appeler NextPDF avant leur réécriture. Considère-la comme une aide à la migration destinée à être supprimée selon un plan, pas comme une dépendance d’exécution permanente. Le nouveau code appelle nextpdf/core (ou l’intégration de framework concernée) directement.

Tourner sur PHP 8.1 ou 7.4

Chaque package de l’écosystème déclare PHP >=8.4 <9.0. nextpdf/backport-builder existe précisément pour cette contrainte : son objectif déclaré est un pipeline de downgrade Rector qui construit un artefact PHP 8.1+ (et une cible 7.4). C’est un outil de build, pas une dépendance d’exécution de ton application. Exécute le builder pour produire le moteur backporté, puis déploie ce moteur.

Un appelant non-PHP ou un agent d’IA

nextpdf/server (NextPDF Connect) expose le moteur via une API REST, un service gRPC et le Model Context Protocol. Choisis-le quand l’appelant est distant, écrit dans un autre langage, ou quand un système d’IA consomme un endpoint d’outil plutôt qu’une bibliothèque PHP. Une application PHP dans le même processus devrait utiliser nextpdf/core ou une intégration de framework plutôt que de payer le coût d’un saut réseau.

Utiliser plusieurs intégrations ensemble

Une intégration de framework et un pont de rendu interviennent à des couches différentes, donc tu peux installer les deux. L’intégration de framework gère le câblage du conteneur et la réponse HTTP ; le pont de rendu gère le backend de rendu. Lorsque tu résous un ensemble combiné de dépendances, vérifie quelles versions de nextpdf/core chaque package accepte. Pour cela, la référence de contrainte du cœur dans l’index du Cookbook d’intégration fait foi. Les recipes propres à chaque combinaison se trouvent dans les dépôts concernés et sont liées depuis cet index.

Voir aussi

• Cookbook d’intégration — référence des packages, des contraintes du cœur et index des liens de recipes.
• Conventions des recipes — le contrat suivi par chaque recipe exécutable.