Guide du développeur CodeIgniter

En bref

Le package CodeIgniter expose des fabriques de services, des helpers et un léger wrapper de bibliothèque Pdf autour d’un document unique. Ce wrapper est pratique dans les contrôleurs. Le travail en file d’attente s’appuie sur des callables statiques de builder, car les charges utiles de file de CodeIgniter sont des données sérialisées.

Utilise ce guide pour concevoir des flux de contrôleur, des services, des builders de file ou des tests autour de nextpdf/codeigniter.

Frontière architecturale

Couche	Détenue par	Responsabilité	Ne pas mettre ici
Contrôleur	Application	Vérifie les autorisations, appelle un builder ou un service, puis renvoie un `DownloadResponse`.	Logique de mise en page partagée.
Wrapper de bibliothèque	`nextpdf/codeigniter`	Encapsule un `Document` et expose des helpers response/save.	Stockage durable de documents.
Fabrique de services	`nextpdf/codeigniter`	Crée des registres partagés et de nouveaux documents.	Racines de stockage métier.
Builder de file	Application	Construit un document à partir d’un callable statique.	Objets de requête ou état non sérialisable.
Moteur principal	`nextpdf/nextpdf`	Construit et sérialise le PDF.	Réponse CodeIgniter ou politique de file.

Cycle de vie à l’exécution

Étape	Comportement	Action du développeur
Enregistrement de l’autoload	`Registrar::Autoload()` enregistre le chargement des helpers du module.	Charge le module via la configuration de CodeIgniter.
Résolution du service	`Services::pdf()` renvoie par défaut un wrapper autour d’un document neuf.	Résous-le une fois par requête.
Rédaction	Le code de l’application utilise `Pdf::document()` pour les appels principaux au document.	Conserve le code de construction du document dans des services ou des builders.
Réponse	`PdfResponse` renvoie un `DownloadResponse`.	Laisse le package définir les en-têtes PDF.
Exécution en file	`GeneratePdfJob::process()` valide le builder et le chemin de sortie, puis enregistre la sortie.	Place les builders de file sous `App\PdfBuilders`.

Structure applicative recommandée

Chemin	Rôle
`app/PdfBuilders/*`	Builders statiques compatibles avec la file et acceptés par `GeneratePdfJob`.
`app/Libraries/*`	Wrappers applicatifs optionnels pour les workflows de document récurrents.
`app/Services/*`	Récupération des données métier et politique de stockage.
`app/Config/NextPdf.php`	Surcharges de configuration propres à l’application.
`tests/app/PdfBuilders/*`	Tests des builders et des charges utiles de file.

Utilise les helpers du package pour les flux courts. Utilise des appels de service explicites quand la construction du document relève d’une classe à tester directement.

<?php

namespace App\Controllers;

final class InvoiceController extends BaseController
{
    public function download(int $id)
    {
        $pdf = pdf();
        $pdf->document()
            ->setTitle('Invoice ' . $id)
            ->addPage()
            ->writeHtml('<h1>Invoice ' . $id . '</h1>');

        return $pdf->download('invoice-' . $id . '.pdf');
    }
}

Modèle de builder de file

Les builders de file doivent être statiques, déterministes et situés sous App\PdfBuilders. Garde le tableau de contexte suffisamment simple pour qu’il soit sérialisable et auditable.

<?php

namespace App\PdfBuilders;

use NextPDF\Core\Document;

final class InvoiceBuilder
{
    public static function build(Document $document, array $context): Document
    {
        $document->setTitle((string) $context['title'])
            ->addPage()
            ->writeHtml((string) $context['html']);

        return $document;
    }
}

Le job limite la sortie au répertoire PDF applicatif configuré. Si ton application a besoin d’un stockage propre à chaque tenant, place cette politique dans un seul service et teste-la avant la mise en file.

Points d’extension

Point d’extension	À utiliser pour	Contrainte
`Services::pdfDocument()`	Personnaliser la création de document.	Doit renvoyer un document neuf.
`Services::fontRegistry()`	Préparer les polices et accéder au registre.	Rejette les chemins dangereux et conserve le registre verrouillé après la préparation.
`Services::pdfSigner()`	Activer la signature numérique optionnelle.	Renvoie `null` quand la signature est désactivée.
`NextPDF\CodeIgniter\Libraries\Pdf`	Wrapper exposé aux contrôleurs.	Un wrapper correspond à un document.
`App\PdfBuilders::*`	Builders de document compatibles avec la file.	Chaîne callable statique requise.
`app/Config/NextPdf.php`	Valeurs par défaut de l’application et paramètres d’intégration.	Garde les valeurs de production explicites.

Workflow de développement

Commence par un contrôleur qui appelle pdf() ou service('pdf').
Déplace la logique répétée de construction de document dans app/PdfBuilders ou un service applicatif.
Utilise GeneratePdfJob quand la génération est trop lente pour le chemin de la requête.
Garde le contexte de file sérialisable et compact.
Stocke la sortie sous la racine de stockage PDF approuvée, sauf si tu étends délibérément la politique.
Ajoute des tests pour les helpers, les services, les charges utiles de file et les chemins dangereux.

Gestion des échecs

Échec	Où le gérer	Réponse recommandée
Extension manquante ou chemin de police dangereux	Fabrique de services.	Fais échouer la résolution du service au plus tôt.
Callable de builder invalide	Validation du job de file.	Rejette le job et journalise la chaîne du builder sans secrets.
Chemin de sortie dangereux	Service de stockage et job de file.	Rejette avant la mise en file et conserve la validation du job.
Erreur de sérialisation de la réponse	Gestion des erreurs du contrôleur ou du framework.	N’envoie aucun corps de réponse partiel.
Classe Premium optionnelle indisponible	Valeur de retour de la méthode de service.	Gère `null` explicitement avant d’utiliser les fonctionnalités e-invoice optionnelles.

Valeurs par défaut sûres

Sujet	Valeur par défaut	Quand surcharger
Namespace des builders de file	`App\PdfBuilders`.	Conserve la valeur par défaut, sauf si tu mets aussi à jour la politique de sécurité.
Racine de sortie	`WRITEPATH/pdfs`.	Ne surcharge qu’avec une allowlist plus stricte.
Nom de fichier de la réponse	`document.pdf`.	Utilise des noms de fichiers métier assainis.
Méthodes de flux	Parité d’API avec les autres frameworks.	Ne considère pas le streaming comme une limite mémoire dans CodeIgniter.
Service de document	Neuf par défaut.	Ne demande pas de documents partagés dans le code de requête.

Liste de vérification des tests

Les tests de service vérifient que chaque résolution de Services::pdf() renvoie un document indépendant.
Les tests de helpers vérifient que pdf() et pdf_document() renvoient des objets neufs.
Les tests de réponse vérifient les en-têtes et la normalisation du nom de fichier.
Les tests de file couvrent les chaînes de builder invalides et les chemins de sortie dangereux.
Les tests de builder s’exécutent avec des données de contexte représentatives.
Les tests de configuration couvrent le chemin des polices, le chemin de cache, la signature désactivée et les états TSA désactivés.