Un seul moteur, tous les frameworks

SpecSpec: PSR-11 Container, §1.1.2PSR-11 Container §1.1.2SpecSpec: PSR-4 Autoloader, §3PSR-4 Autoloader §3

En bref

La plupart des parcs PHP qui grandissent finissent avec plus d’un framework. NextPDF est un moteur PDF unique qui rencontre chacun d’eux selon ses propres termes : des ponts idiomatiques pour Laravel, Symfony et CodeIgniter, plus un chemin autonome pour le code qui ne tourne dans aucun d’eux. Le modèle de document est partagé. Seule la façon dont tu l’appelles change.

Pourquoi c’est important

Une bibliothèque PDF différente par pile est une taxe silencieuse. Chacune a ses propres bizarreries, sa propre gestion des polices, sa propre idée de ce que « valide » veut dire. Une facture qui se rend correctement depuis le service Laravel peut se rendre subtilement différemment depuis le worker Symfony, parce qu’une bibliothèque différente l’a dessinée. Désormais ta cible d’archivage, le placement de ta signature et tes balises d’accessibilité dépendent de quelle équipe a livré le document. Le rapport de bug dit « le PDF est faux », et la réponse dépend de lequel des trois moteurs l’a produit.

Standardiser sur un seul moteur fait s’effondrer cette surface. Il y a un seul endroit où un profil PDF/A est décidé, un seul pipeline de polices à certifier, un seul validateur en qui avoir confiance. Le framework dans lequel tu te trouves cesse d’être une variable dans la question de savoir si le document est correct.

La version courte

• Le moteur du cœur est indépendant des frameworks. nextpdf/core ne sait rien de HTTP, du routage ni du câblage de conteneur. C’est un moteur PDF 2.0 et rien de plus.
• Chaque pont adapte, il ne réimplémente pas. Les paquets Laravel, Symfony et CodeIgniter te donnent une façade ou une fabrique, une aide de réponse HTTP, et un chemin de génération en file d’attente ou asynchrone — par-dessus le même moteur.
• Un pont suit ton framework, pas ton document. Il change la façon dont tu appelles le moteur, jamais ce que le moteur peut produire.
• L’autonome est toujours disponible. Un outil CLI, un démon ou une bibliothèque n’a aucun framework duquel faire le pont ; il construit un document directement.
• Un seul modèle de document voyage à travers les quatre. Les mêmes objets-valeurs, énumérations et contrat de sortie apparaissent partout, si bien qu’un document se déplace entre les points d’appel sans changer.

L’approche de NextPDF

L’architecture est une scission délibérée. Le moteur est l’actif ; le pont est un adaptateur fin qui parle les idiomes d’un framework. Un pont enregistre un petit espace de noms par-dessus le cœur partagé via l’autoload standard (SpecSpec: PSR-4 Autoloader, §3PSR-4 Autoloader §3) et renvoie un document via le contrat de conteneur (SpecSpec: PSR-11 Container, §1.1.2PSR-11 Container §1.1.2). Ce contrat est le héros discret ici : il autorise deux résolutions du même identifiant à renvoyer des instances différentes, ce qui est exactement la façon dont un pont te donne un document frais et jetable par requête tout en gardant le registre de polices analysées et le cache d’images comme des singletons à l’échelle du processus. Les workers à longue durée de vie — Octane, RoadRunner, Swoole, Messenger — obtiennent une analyse de polices amortie sans fuite d’état entre requêtes, par construction.

Les quatre idiomes ne diffèrent qu’en surface :

1. Core enginenextpdf/core — the framework-agnostic PDF 2.0 engine; the single shared document model, value objects, and output contract.
2. Laravel bridgenextpdf/laravel — auto-discovered provider, a Pdf facade, a PdfResponse helper, and a queued GeneratePdfJob.
3. Symfony bridgenextpdf/symfony — an auto-registered bundle, an injectable PdfFactory, a PdfResponse, and an optional Messenger handler.
4. CodeIgniter bridgenextpdf/codeigniter — a service and pdf() helper, a Pdf library over a disposable Document, and a PdfResponse.
5. StandaloneNo framework to bridge from — construct a Document directly in a CLI tool, daemon, or library.

Un seul moteur cœur indépendant des frameworks atteint par quatre surfaces idiomatiques : une façade Laravel, une fabrique Symfony injectée, un service CodeIgniter, ou un document autonome construit directement — chacun renvoyant le même modèle Document jetable.

Lis le schéma de gauche à droite et la leçon est la symétrie. Chaque surface résout vers le même Document. La façade Laravel, la fabrique Symfony, le service CodeIgniter et le constructeur autonome sont quatre portes vers une même pièce.

Exemple pratique

Les mêmes trois lignes d’intention, exprimées dans chaque idiome. Le corps qui construit le document — pages, polices, cellules, signature, conformité — est identique dans les quatre, parce que c’est le même moteur.

<?php

declare(strict_types=1);

// Laravel — resolve a fresh document from the container.
use NextPDF\Contracts\PdfDocumentInterface;
$document = app(PdfDocumentInterface::class);

// Symfony — inject the factory, then ask it for a document.
use NextPDF\Symfony\Service\PdfFactory;
$document = $factory->create(); // PdfFactory injected into your service

// CodeIgniter — pull it from the Services layer.
use NextPDF\CodeIgniter\Config\Services;
$document = Services::pdfDocument();

// Standalone — no framework; construct it directly.
use NextPDF\Core\Document;
$document = Document::createStandalone();

// From here, the code is identical regardless of how $document arrived.
$document->addPage();
$document->cell(0, 10, 'One engine, every framework', newLine: true);
$bytes = $document->getPdfData();

Les premières lignes sont la seule différence. Tout ce qui suit est portable : déplace un service de construction de document de Symfony vers un worker autonome et le code de rendu ne change pas, parce que le contrat dont il dépend n’a pas changé.

Human-factors note:Human-factors note

Standardiser est une décision d’équipe plus qu’une décision technique. Quand chaque pile dessine ses PDF avec le même moteur, une correction du pipeline de polices ou un resserrement du profil d’archivage atterrit une seule fois et atteint tout le monde. Les relecteurs apprennent une seule API. Un nouveau service hérite gratuitement du chemin certifié. Le coût est d’adopter une dépendance par framework ; l’économie est que « le PDF est faux » cesse d’être une question sur laquelle bibliothèque l’a dessiné.

Idée fausse courante

L’hypothèse fréquente est que le pont de framework déverrouille des capacités — que la validation de signature à long terme ou la facturation électronique structurée arrive parce que tu as installé nextpdf/laravel plutôt que d’appeler le moteur directement. Ce n’est pas le cas. Un pont change le point d’appel, jamais la portée du moteur. Les capacités du cœur telles que la sortie PDF/A et la signature PAdES de référence sont open source et atteignent chaque surface ; les capacités avancées sont déverrouillées par une édition et sont alors disponibles à travers n’importe quel pont ou le chemin autonome de façon égale. Choisir une intégration de framework n’est pas choisir un jeu de fonctionnalités.

L’idée fausse miroir est qu’« un seul moteur » devrait signifier un seul chemin de rendu pour chaque document. Ce n’est pas le cas. Le moteur en cours de processus rend le PDF directement ; quand un document a réellement besoin d’un moteur de mise en page de niveau navigateur, un paquet de rendu s’en charge. Le rendu et l’invocation sont des axes distincts — le guide de décision d’intégration est l’endroit qui les cartographie.

Limites et frontières

Un pont n’élargit pas ce que le moteur peut rendre. C’est la limite honnête, et c’est tout l’enjeu : la capacité vit dans le cœur et le palier, pas dans l’adaptateur à travers lequel tu l’atteins.

Framework bridges over one engine — edition availability

Edition	Availability
Core	○ Chaque pont (Laravel, Symfony, CodeIgniter) et le chemin autonome sont Apache-2.0 et fonctionnent au-dessus de Core. Ils adaptent ou exposent le moteur ; ils ne verrouillent pas de fonctionnalités et ne changent pas ce qu’il peut produire.
Pro	○ Les capacités avancées telles que la validation de signature à long terme (PAdES B-LT et B-LTA) sont déverrouillées par une édition, puis atteintes identiquement à travers n’importe quel pont ou en autonome — jamais en changeant de framework. La sortie d’archivage PDF/A et la signature PAdES de référence (B-B et B-T) sont déjà dans Core, disponibles de la même manière à travers chaque surface.
Enterprise	○ La facturation électronique structurée (EN 16931) et l’outillage de conformité plus poussé sont aussi des capacités d’édition, de même identiques quelle que soit la surface qui appelle le moteur, tandis que la validation de conformité elle-même est livrée dans Core.

Deux frontières supplémentaires méritent d’être énoncées clairement. Premièrement, chaque pont suit une majeure courante de son framework — Laravel, Symfony et CodeIgniter fixent chacun une plage prise en charge, si bien que « tous les frameworks » signifie la version prise en charge de chacun, pas chaque version historique ; traite la documentation propre à chaque paquet comme la référence faisant autorité pour son API. Deuxièmement, les ponts sont des adaptateurs de framework, pas des backends de rendu. Si un document a besoin d’un moteur de mise en page complet de navigateur, c’est un choix de moteur de rendu indépendant de quel framework a appelé le moteur.

Documents associés

• Le guide de décision d’intégration — la carte cas d’usage vers paquet, y compris les moteurs de rendu et la surface du service Connect, quand tu as besoin de décider plutôt que de standardiser.
• Cœur ouvert, sans verrouillage — pourquoi le moteur est l’actif et les ponts sont fins, si bien que standardiser ne te piège pas.
• Le pipeline HTML — ce que le moteur en cours de processus couvre, pour savoir quand un moteur de rendu navigateur est la question distincte.
• Les fondations PHP 8.4 — le socle d’exécution que chaque pont et le chemin autonome partagent.

Glossaire

• Moteur du cœur — nextpdf/core, le moteur PDF 2.0 indépendant des frameworks sur lequel chaque pont et le chemin autonome se bâtissent.
• Pont de framework — un paquet d’intégration (Laravel, Symfony, CodeIgniter) qui adapte le moteur aux idiomes d’un framework — façade, fabrique, réponse, tâche en file d’attente — sans changer ses capacités.
• Chemin autonome — utiliser le moteur du cœur directement, sans framework, en construisant toi-même un Document ; la voie pour les outils CLI, les démons et les bibliothèques.
• Document jetable — le contrat Document à usage unique : construire, émettre, jeter. Chaque résolution de conteneur en renvoie un frais, si bien qu’aucun état ne fuit entre les requêtes dans un worker à longue durée de vie.
• PAdES — PDF Advanced Electronic Signatures, la famille de profils ETSI pour la signature PDF. La signature de référence (B-B et B-T) est dans Core ; la validation à long terme (B-LT et B-LTA) est une capacité d’édition avancée. L’une comme l’autre est atteinte à travers n’importe quelle surface, traitée en profondeur sur les pages de signature.