Référence de l'API Symfony

En un coup d’œil

Le package Symfony expose l’enregistrement du bundle, un arbre de configuration, une fabrique injectable qui crée des documents neufs, des aides de réponse HTTP et des types Messenger pour la génération asynchrone. Dans la plupart des cas, ton code applicatif ne touche que deux symboles : le service PdfFactory, que tu injectes pour construire un Document, et l’aide PdfResponse, qui transforme ce document en réponse HTTP sécurisée. Les autres symboles (bundle, extension, compiler pass, arbre de configuration, DTO Messenger et handler) relèvent du câblage que tu configures une seule fois, ou que le framework gère pour toi.

Commence ici : si tu débutes, injecte NextPDF\Symfony\Service\PdfFactory, appelle create() pour obtenir un Document neuf, puis renvoie-le avec NextPDF\Symfony\Http\PdfResponse::download(). Le premier exemple ci-dessous fait exactement cela.

Tâches courantes

Trois extraits exécutables couvrent les tâches les plus fréquentes. Chacun n’utilise que les symboles vérifiés et documentés dans les tableaux qui suivent.

Renvoyer un téléchargement de PDF depuis un contrôleur — injecte la fabrique, construis un document, puis confie-le à l’aide de réponse :

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class InvoiceController
{
    #[Route('/invoice/{number}', name: 'invoice_pdf')]
    public function download(PdfFactory $pdf, string $number): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, "Invoice #{$number}");

        return PdfResponse::download($doc, "invoice-{$number}.pdf");
    }
}

Ce que fait cet exemple : PdfFactory::create() retourne un Document neuf et préconfiguré. PdfResponse::download() l’envoie avec Content-Type: application/pdf, une disposition en pièce jointe et les en-têtes de sécurité fixes du bundle.

Diffuser un gros PDF en streaming pour limiter le pic mémoire — change d’aide et renvoie une StreamedResponse :

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\StreamedResponse;
use Symfony\Component\Routing\Attribute\Route;

final class ReportController
{
    #[Route('/report', name: 'report_pdf')]
    public function report(PdfFactory $pdf): StreamedResponse
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, 'Annual report');

        return PdfResponse::streamDownload($doc, 'annual-report.pdf');
    }
}

Ce que fait cet exemple : PdfResponse::streamDownload() émet par fragments le PDF matérialisé et omet Content-Length ; utilise streamInline() pour l’équivalent en ligne.

Dispatcher un PDF pour une génération asynchrone — envoie un GeneratePdfMessage à un transport Messenger pour que le rendu s’exécute sur un worker :

<?php

declare(strict_types=1);

namespace App\Controller;

use App\Pdf\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Routing\Attribute\Route;

final class QueueController
{
    #[Route('/invoice/{id}/queue', name: 'invoice_queue')]
    public function queue(MessageBusInterface $bus, int $id): Response
    {
        $bus->dispatch(new GeneratePdfMessage(
            builderClass: InvoicePdfBuilder::class,
            outputPath: '/var/storage/invoices/' . $id . '.pdf',
            builderContext: ['invoice_id' => $id],
        ));

        return new Response('PDF generation queued.', 202);
    }
}

Ce que fait cet exemple : le DTO contient une class-string de builder et un chemin de sortie validé. Le handler résout le builder, construit le document, puis l’enregistre côté worker. La classe de builder implémente PdfBuilderInterface et est enregistrée dans un service locator (consulte le quickstart Symfony pour le câblage du locator et du worker).

Fabrique

Consulte ce tableau quand tu as besoin de la signature exacte du constructeur et du contrat create() du service injectable qui produit des documents neufs.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)`	`factory` : fabrique du cœur ; `defaults` : créateur, auteur, langue, marges ; `pdfa` : profil PDF/A optionnel ; `artisanConfig` : config optionnelle du renderer Chrome.	Les valeurs par défaut ne sont appliquées que si elles sont configurées.	`PdfFactory`	Erreurs de câblage du conteneur.	Le service peut être un singleton, car `create()` retourne un document neuf.
`PdfFactory::create()`	aucun.	Applique le créateur et la langue ; applique l’auteur uniquement s’il est non vide ; applique la config PDF/A et Artisan uniquement si elle est disponible.	`NextPDF\Core\Document`	Erreurs de configuration du cœur.	À utiliser une fois par requête, commande ou message.
`PdfFactory::setArtisanAvailable(bool $available)`	`available` : drapeau de disponibilité à la compilation.	Désactivé jusqu’à ce que le compiler pass l’active.	`void`	aucun attendu.	Hook interne appelé par le compiler pass optionnel de l’extension.
`PdfFactory::setProAvailable(bool $available)`	`available` : drapeau de disponibilité à la compilation.	Désactivé jusqu’à ce que le compiler pass l’active.	`void`	aucun attendu.	Hook interne pour la disponibilité Premium.

Bundle, extension et configuration

Ce tableau décrit la couche de câblage : consulte-le quand tu enregistres le bundle, résous l’arbre de configuration nextpdf ou diagnostiques la détection des extensions optionnelles. Le second tableau liste les clés de configuration elles-mêmes.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`NextPdfBundle::build(ContainerBuilder $container)`	Container builder de Symfony.	Appelle la méthode build parente et enregistre `OptionalExtensionPass`.	`void`	Erreurs d’enregistrement du compiler pass.	Active la détection optionnelle des fonctionnalités Artisan et Premium.
`NextPdfBundle::getPath()`	aucun.	Retourne le chemin racine du package.	`string`	aucun attendu.	Utilisé par la découverte de bundles de Symfony et le chargement des ressources.
`NextPdfExtension::load(array $configs, ContainerBuilder $container)`	Tableaux de config utilisateur et container builder.	Traite la config `nextpdf`, stocke les paramètres résolus, charge les définitions de services, puis vérifie les extensions requises.	`void`	Erreurs de validation de config, de chargement des services ou d’extension manquante.	Les extensions requises sont `mbstring` et `zlib`.
`NextPdfExtension::getAlias()`	aucun.	Utilise `nextpdf` comme clé de config racine.	`string`	aucun attendu.	Configure le bundle sous `nextpdf:`.
`Configuration::getConfigTreeBuilder()`	aucun.	Définit l’arbre de configuration `nextpdf` validé.	`TreeBuilder`	Erreurs de définition de config de Symfony.	Reflète la forme de config de Laravel autant que possible.
`OptionalExtensionPass::process(ContainerBuilder $container)`	Container builder de Symfony.	Détecte les services optionnels Artisan et Premium et bascule les drapeaux de disponibilité de la fabrique.	`void`	Erreurs de câblage du compiler pass.	S’exécute pendant la compilation du conteneur.

Clé de config	Type	Comportement par défaut	Notes
`page_format`	enum	`A4` ; les valeurs autorisées incluent `A3`, `A5`, `Letter`, `Legal` et `Tabloid`.	S’applique à la création de document par défaut.
`orientation`	enum	`P` ; les valeurs autorisées sont `P` et `L`.	Utilise des appels explicites sur le document lorsqu’une page doit changer d’orientation.
`unit`	enum	`mm` ; les valeurs autorisées sont `pt`, `mm`, `cm` et `in`.	Maintient les valeurs par défaut du framework alignées sur les unités du cœur.
`pdfa`	`string	null`	`null` ; les valeurs autorisées sont `4`, `4e` et `4f`.
`fonts_path` / `cache_path`	`string`	Chemin des polices du projet et chemin du cache du kernel.	Assure-toi que les deux chemins sont lisibles ou accessibles en écriture selon le rôle d’exécution.
`signature.*`	`array`	Désactivé par défaut avec le niveau de signature `B-B`.	Fournit le certificat, la clé, le mot de passe, les certificats supplémentaires et le niveau.
`tsa.*`	`array`	Désactivé quand l’URL vaut `null` ; le timeout est de 30 secondes par défaut.	Prend en charge les identifiants, les fichiers mTLS, les pins de clé publique et la politique HTTP.
`ocsp_cache.*`	`array`	Activé avec un TTL de 86400 secondes.	Utilisé par les flux de validation et de signature à long terme quand il est disponible.
`messenger.*`	`array`	Transport `async`, timeout 120, 3 tentatives.	Utilisé par les workflows de génération asynchrone.
`artisan.*`	`array`	Renderer Chrome désactivé tant qu’il n’est pas configuré et installé.	Correspond à `ChromeRendererConfig` quand le renderer optionnel est disponible.
`defaults.*`	`array`	Créateur `NextPDF`, auteur vide, langue `en`, marges et police par défaut.	Appliqué par `PdfFactory::create()`.

Réponses HTTP

Utilise ce tableau pour choisir la bonne aide de réponse — affichage en ligne ou téléchargement, avec mise en mémoire tampon ou en streaming — et pour connaître le comportement de chacune sur le nom de fichier et les en-têtes.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document` : document construit ; `filename` : nom de fichier de la réponse.	Ajoute `.pdf` s’il manque.	`Symfony\Component\HttpFoundation\Response`	Erreurs de sérialisation du cœur.	Définit le content type PDF et des en-têtes défensifs.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Identique à `inline` ; la disposition est en pièce jointe.	Réponse de téléchargement dans le navigateur.	`Response`	Identique à `inline`.	À utiliser pour les téléchargements explicites.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Identique à `inline`.	Émet les octets du PDF matérialisé par fragments.	`StreamedResponse`	Identique à `inline`.	N’évite pas la matérialisation du document.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Identique à `streamInline` ; la disposition est en pièce jointe.	Téléchargement en streaming.	`StreamedResponse`	Identique à `streamInline`.	Applique la politique de taille de sortie avant le rendu.

Messenger

Consulte ce tableau quand tu mets en place le chemin asynchrone : le DTO de message que tu dispatches, l’interface de builder que tu implémentes et le handler qui s’exécute sur le worker.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])`	`builderClass` : class-string implémentant `PdfBuilderInterface` ; `outputPath` : cible `.pdf` ; `builderContext` : données sérialisables.	Tableau de contexte vide.	DTO de message.	`InvalidArgumentException` pour un FQCN invalide, un wrapper de flux, un octet nul, une traversée de répertoire, un chemin vide ou une cible qui ne finit pas par `.pdf`.	Les transports Messenger transportent des données, pas des closures.
`PdfBuilderInterface::build(Document $document, array $context): Document`	`document` : document neuf et configuré ; `context` : données de message sérialisables.	Aucun contexte par défaut en dehors de la valeur portée par le message.	Le `Document` configuré.	Exceptions spécifiques au builder.	Garde les builders déterministes et idempotents.
`new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)`	Fabrique PDF et service locator de builders taggés.	Aucun document n’est créé à la construction.	`GeneratePdfHandler`	Erreurs de câblage du conteneur.	Le locator devrait n’exposer que des implémentations de `PdfBuilderInterface`.
`GeneratePdfHandler::__invoke(GeneratePdfMessage $message)`	`message` : DTO de message validé.	Résout le builder depuis le conteneur, construit le document, puis l’enregistre.	`void`	Service de builder manquant, résultat de builder invalide, erreurs d’écriture du cœur.	Préfère des builders déclarés comme services aux callbacks statiques.

Notes de développement

Ne stocke pas un Document comme service. Stocke PdfFactory et appelle create() pour chaque unité de travail.
Ne mets en file d’attente que du contexte sérialisable. Ne mets pas de flux ouverts, de closures ni d’objets de requête dans builderContext.
Garde une politique de chemin de sortie plus stricte que le DTO lorsque le déploiement utilise des racines de stockage spécifiques au tenant.