Référence API CodeIgniter

En un coup d’œil

Le package CodeIgniter expose une petite surface orientée contrôleur : un wrapper de bibliothèque Pdf autour d’un document unique (Services::pdf() et l’assistant global pdf()), des assistants de réponse qui convertissent un document construit en DownloadResponse (PdfResponse), les fabriques Services qui les sous-tendent (registres de polices et d’images, fabrique de documents, signataire optionnel et client TSA), la classe de configuration NextPdf, ainsi qu’un GeneratePdfJob pour la génération asynchrone à partir de callables de constructeur statiques.

Commence ici : dans un contrôleur, appelle Services::pdf() (ou l’assistant pdf()), ajoute du contenu à $pdf->document(), puis retourne $pdf->download('file.pdf'). À lui seul, ce chemin couvre la tâche la plus courante. Les tableaux de référence ci-dessous sont organisés par surface d’API ; la section Tâches courantes présente d’abord les formes exécutables.

Tâches courantes

Voici les flux réels les plus fréquents. Chaque exemple a été vérifié dans les sources de nextpdf/codeigniter.

Retourner un PDF téléchargeable depuis un contrôleur : le chemin de rendu de référence :

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, "Invoice #{$id}");

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

Ce que cela fait : résout un nouveau Pdf qui enveloppe un nouveau Document, écrit une cellule et retourne un DownloadResponse avec une disposition attachment et les en-têtes de sécurité du package.

Prévisualiser un PDF dans le navigateur : même wrapper, inline() au lieu de download() :

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;

final class ReportController extends BaseController
{
    public function preview(): DownloadResponse
    {
        $pdf = pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly Report');

        return $pdf->inline('report.pdf');
    }
}

Ce que cela fait : utilise l’assistant global pdf() (équivalent à Services::pdf()) et retourne un DownloadResponse avec une disposition inline pour que le navigateur affiche le PDF au lieu de le télécharger.

Générer un PDF de façon asynchrone via la file d’attente : place GeneratePdfJob dans la file avec un constructeur statique :

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

service('queue')->push('pdf', GeneratePdfJob::class, [
    'builder'    => 'App\PdfBuilders\InvoiceBuilder::build',
    'outputPath' => WRITEPATH . 'pdfs/invoice-42.pdf',
    'context'    => ['invoice_id' => 42],
]);

Ce que cela fait : met la génération en file d’attente. Le worker valide le constructeur (qui doit être un callable statique App\PdfBuilders\...::method) et le chemin de sortie (qui doit se résoudre sous WRITEPATH/pdfs/ et se terminer par .pdf), construit un nouveau document, puis le sauvegarde.

Wrapper de bibliothèque

Consulte ce tableau quand tu as un wrapper Pdf et que tu as besoin de ses méthodes de réponse ou de sauvegarde.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
NextPDF\CodeIgniter\Libraries\Pdf / new Pdf(Document $document)	document : nouveau document du cœur.	Enveloppe le document fourni pour une seule opération de réponse ou de sauvegarde.	Pdf	aucune attendue.	Ne réutilise pas le wrapper après la sortie.
Pdf::document()	aucun.	Retourne le document enveloppé.	NextPDF\Core\Document	aucune attendue.	Utilise cette méthode pour appeler les API d’écriture du cœur.
Pdf::inline(string $filename = 'document.pdf')	filename : nom de fichier de la réponse.	Disposition inline dans le navigateur.	CodeIgniter\HTTP\DownloadResponse	Erreurs de sérialisation du cœur.	Délègue à PdfResponse::inline().
Pdf::download(string $filename = 'document.pdf')	filename : nom de fichier de la réponse.	Disposition attachment dans le navigateur.	DownloadResponse	Erreurs de sérialisation du cœur.	Délègue à PdfResponse::download().
Pdf::streamInline(string $filename = 'document.pdf')	filename : nom de fichier de la réponse.	Parité d’API avec les autres packages de framework.	DownloadResponse	Erreurs de sérialisation du cœur.	CodeIgniter gère nativement la sortie binaire.
Pdf::streamDownload(string $filename = 'document.pdf')	filename : nom de fichier de la réponse.	Parité d’API avec les autres packages de framework.	DownloadResponse	Erreurs de sérialisation du cœur.	Utilise les mêmes contrôles de taille que les réponses non diffusées en flux.
Pdf::save(string $path)	path : cible du système de fichiers.	Écrit le document enveloppé.	void	Erreurs du système de fichiers ou d’écriture du cœur.	Valide les racines de stockage avant de sauvegarder.

Services et assistants

Consulte ce tableau quand tu as besoin d’une fabrique de service précise ou de l’une des fonctions d’assistance globales, et que tu veux connaître son comportement de partage ainsi que son type de retour.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
Services::fontRegistry(bool $getShared = true)	getShared : drapeau de service partagé de CodeIgniter.	Registre partagé, préchargé avec les polices configurées, puis verrouillé.	FontRegistryInterface	RuntimeException en cas d’extensions manquantes ou de chemin de police non sûr.	Rejette les wrappers de flux et les octets nuls dans fontsPath.
Services::imageRegistry(bool $getShared = true)	getShared : drapeau de service partagé.	Registre d’images LRU partagé et limité.	ImageRegistry	aucune attendue.	La taille du cache est contrôlée par imageCacheMb.
Services::documentFactory(bool $getShared = true)	getShared : drapeau de service partagé.	Fabrique partagée qui utilise des registres partagés.	DocumentFactoryInterface	Erreurs de configuration des registres.	La fabrique est réutilisable ; les documents ne le sont pas.
Services::tsaClient(bool $getShared = true)	getShared : drapeau de service partagé.	Retourne null quand tsa.url est vide.	`TsaClient	null`	Erreurs du client HTTP ou de configuration TSA.
Services::pdfSigner(bool $getShared = false)	getShared : drapeau de service partagé.	Retourne null quand la signature est désactivée.	`SignerInterface	null`	Erreurs de certificat ou de niveau de signature.
Services::pdfDocument(bool $getShared = false)	getShared : drapeau de service partagé.	Crée un nouveau document, applique les valeurs par défaut et configure optionnellement PDF/A ou Artisan.	Document	Erreurs optionnelles d’extension ou de configuration de document.	Conserve la valeur false par défaut pour la sécurité des requêtes.
Services::pdf(bool $getShared = false)	getShared : drapeau de service partagé.	Crée un nouveau wrapper Pdf autour d’un nouveau document.	NextPDF\CodeIgniter\Libraries\Pdf	Erreurs de configuration du document.	Principal service orienté contrôleur.
Services::eInvoiceEmbedder()	aucun.	Retourne null sauf si la classe d’intégration d’e-facture Premium Pro existe.	`EmbedderInterface	null`	Erreurs optionnelles de construction de package.
Services::eInvoiceValidator()	aucun.	Retourne null sauf si la classe de validateur Premium Enterprise existe.	`ValidatorInterface	null`	Erreurs optionnelles de construction de package.
Services::eInvoiceProfile()	aucun.	Retourne le profil EN16931 quand Premium Pro est installé.	`ProfileInterface	null`	Erreurs optionnelles de package.
Services::schematronRunner()	aucun.	Retourne null sauf si le validateur Schematron Premium Enterprise existe.	`SchematronRunnerInterface	null`	Erreurs optionnelles de construction de package.
Registrar::Autoload()	aucun.	Ajoute l’assistant du package à la configuration d’autoload de CodeIgniter.	array	aucune attendue.	Active pdf() et pdf_document() quand le module est chargé.
pdf()	aucun.	Appelle Services::pdf(false).	Pdf	Erreurs de configuration du document.	Assistant pratique pour les contrôleurs.
pdf_document()	aucun.	Appelle Services::pdfDocument(false).	Document	Erreurs de configuration du document.	Assistant pratique quand tu préfères l’API de document du cœur.

Réponses HTTP

Consulte ce tableau quand tu as déjà un Document construit et que tu veux construire toi-même le DownloadResponse au lieu de passer par le wrapper Pdf.

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.	Garantit l’extension .pdf et la disposition inline.	DownloadResponse	Erreurs de sérialisation du cœur.	Ajoute le type de contenu PDF et des en-têtes de sécurité.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Identique à inline ; la disposition est attachment.	Garantit l’extension .pdf.	DownloadResponse	Identique à inline.	À utiliser pour les téléchargements depuis le navigateur.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Identique à inline.	Même comportement que inline dans CI4.	DownloadResponse	Identique à inline.	Existe pour la parité d’API entre frameworks.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Identique à download.	Même comportement que download dans CI4.	DownloadResponse	Identique à download.	Existe pour la parité d’API entre frameworks.

Job de file d’attente

Consulte ce tableau quand tu configures la génération asynchrone et que tu as besoin des clés exactes des données du job ainsi que du contrat du callable de constructeur.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
GeneratePdfJob::process()	Clés de données du job : builder, outputPath, context optionnel.	Utilise un tableau de contexte vide quand il est omis.	void	InvalidArgumentException pour un constructeur ou un chemin de sortie non sûr ; erreurs d’écriture du cœur.	Le constructeur doit être App\PdfBuilders\...\*::method.
Callable de constructeur	Document $doc, array $context.	Aucun contexte par défaut au-delà des données de job.	Document	Exceptions spécifiques au constructeur.	Un callable statique est requis car les charges utiles de file d’attente CI4 sont des données sérialisées.

Configuration

Consulte ce tableau quand tu modifies les valeurs par défaut de la classe de configuration NextPdf : format de page, chemins, signature, TSA ou métadonnées de document.

Propriété	Type	Comportement par défaut	Notes
pageFormat	string	A4.	Format de page par défaut.
orientation	string	P.	Orientation par défaut.
unit	string	mm.	Unité par défaut.
pdfa	`string	null`	null.
fontsPath / cachePath	string	WRITEPATH . 'fonts' et WRITEPATH . 'cache/nextpdf'.	Garde les chemins à l’intérieur du stockage contrôlé par l’application.
signature	array	Désactivé avec le niveau B-B.	Certificat, clé, mot de passe, certificats supplémentaires et niveau.
tsa	array	Désactivé quand l’URL est null ; délai d’expiration de 30 secondes.	Identifiants, fichiers mTLS, épingles de clé publique et politique HTTP.
ocspCache	array	Activé avec un TTL de 86400 secondes.	Utilisé par les flux de validation de signature lorsqu’il est disponible.
preloadFonts	list<string>	Vide.	Préchargé avant le verrouillage du registre.
imageCacheMb	int	50.	Contrôle le cache d’images dont la durée de vie est celle du processus.
fontCacheLocking	bool	true.	Maintient les mutations du registre de polices hors du cycle de gestion des requêtes.
artisan	array	Le renderer Chrome est désactivé sauf s’il est configuré et installé.	Est mappé sur ChromeRendererConfig::fromArray().
defaults	array	Créateur NextPDF, auteur vide, langue en, marges et police par défaut.	Services::pdfDocument() applique uniquement creator, language et (quand il est non vide) author ; les clés margin_top/right/bottom/left, font_family, font_size, trim_box et bleed_box sont des valeurs par défaut définies qu’il n’applique pas actuellement.

Notes de développement

• GeneratePdfJob limite la sortie à WRITEPATH . 'pdfs' et exige .pdf.
• Les callables de constructeur situés en dehors de App\PdfBuilders sont rejetés pour éviter l’exécution de code arbitraire à partir de charges utiles de file d’attente modifiées.
• Utilise service('pdf') ou l’assistant du package pour les flux de contrôleur ; utilise des jobs de file d’attente pour la génération de longue durée.