Intégration NextPDF pour Laravel

En bref

Ce guide pratique t’accompagne dans l’intégration de NextPDF à une application Laravel 12. Tu avances en six étapes : installe le package, laisse Laravel le découvrir automatiquement, publie la configuration, résous les liaisons du conteneur, renvoie une réponse HTTP et exécute un job en file d’attente. Chaque étape renvoie vers la référence détaillée du domaine concerné.

Installation

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Démarrage / découverte automatique

Laravel découvre automatiquement le service provider et l’alias de façade à partir du bloc composer.jsonextra.laravel du package. Tu n’as pas besoin de modifier config/app.php. La table d’autoload ne contient qu’une seule entrée PSR-4. Le préfixe NextPDF\Laravel\ se résout en src/Laravel/, selon la règle PSR-4 qui fait correspondre un préfixe à un répertoire de base (PSR-4 §3). Le provider est différé. Il s’initialise lorsque l’une de ses entrées provides() est résolue pour la première fois. Les détails complets du mécanisme de découverte sont disponibles dans /integrations/laravel/boot-and-discovery/.

Liaisons du conteneur

Résous le contrat de document à partir du conteneur. Un identifiant lié se résout en son entrée enregistrée (PSR-11 §1.1.2). La liaison du document est une factory : chaque résolution te donne donc un document neuf. Les registres de polices et d’images sont des singletons : chaque résolution renvoie donc la même instance partagée. La table complète des durées de vie des liaisons est disponible dans /integrations/laravel/overview/ et /integrations/laravel/boot-and-discovery/.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Wired through the container', newLine: true);

Publier la configuration

php artisan vendor:publish --tag=nextpdf-config

Cette commande écrit config/nextpdf.php. Chaque clé, sa variable d’environnement et sa valeur par défaut sont documentées dans /integrations/laravel/configuration/.

Test de fumée du service provider / bundle

Le package fournit une suite de tests basée sur Testbench qui vérifie le provider de bout en bout. Voici un test de fumée minimal que tu peux ajouter à une application consommatrice :

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

Ces deux assertions reprennent les vérifications de conformité use-once effectuées par le EInvoiceServiceProviderIntegrationTest du package lui-même. Elles confirment que le document est lié en factory et que le registre de polices est un singleton verrouillé.

Points d’entrée de l’API publique

Point d’entrée	Rôle	Référence
`NextPDF\Laravel\Facades\Pdf`	Proxy statique vers un document neuf	/integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	Document résolu par le conteneur	/integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	Réponses HTTP en ligne / téléchargement / en flux	/integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	Génération en file d’attente	/integrations/laravel/production-usage/

Exemple de code — Production

Le contrôleur câblé par injection de dépendances, avec gestion des erreurs, est documenté en détail dans /integrations/laravel/production-usage/. Le job en file d’attente l’est aussi, avec ses callbacks de succès et d’échec.

Cas limites & pièges

Résous PdfDocumentInterface, et non la classe concrète Document. Cela garde la liaison testable et interchangeable.
SignerInterface et TsaClient se résolvent en null tant qu’ils ne sont pas configurés. Vérifie toujours cette valeur null.
Les contrats e-invoice nécessitent nextpdf/premium. Ils sont liés, mais déclenchent une erreur à la première résolution si celui-ci est absent.

Performance

Le câblage de bout en bout n’ajoute aucun coût de démarrage, car le provider est différé. Les coûts de construction lors de la première résolution et ceux de préchauffage des polices sont traités dans /integrations/laravel/boot-and-discovery/.

Notes de sécurité

PdfResponse applique un ensemble fixe d’en-têtes OWASP. GeneratePdfJob valide son chemin de sortie dans le worker. Le modèle de menace est décrit dans /integrations/laravel/security-and-operations/.

Conformité

Affirmation	Source	Clause	reference_id
Un identifiant lié se résout en son entrée enregistrée	Conteneur PSR-11	§1.1.2
Le préfixe PSR-4 correspond au répertoire de base	Autoloader PSR-4	§3

Contexte commercial

Les contrats de signature, PDF/A et e-invoice s’intègrent via le même provider lorsque nextpdf/premium est installé. Il s’agit d’une capacité Enterprise optionnelle. Le package Core documenté ici ne nécessite aucune modification de code pour l’adopter. Voir https://nextpdf.dev/get-license/?intent=laravel-signing.

Voir aussi

/integrations/laravel/overview/ — architecture et table des liaisons
/integrations/laravel/install/ — installation et extensions optionnelles
/integrations/laravel/quickstart/ — premier exemple exécutable
/integrations/laravel/production-usage/ — injection de dépendances, gestion des erreurs, file d’attente
/integrations/laravel/boot-and-discovery/ — découverte et durées de vie