Démarrage et découverte de NextPDF dans CodeIgniter

En bref

CodeIgniter 4 détecte automatiquement la classe Services du package, ses fonctions helper et son registrar grâce à la découverte des packages Composer. Cette page décrit la séquence exacte et la configuration qui pilote cette découverte.

Fonctionnement de la découverte des Services CodeIgniter

CodeIgniter 4 résout un service en parcourant toutes les classes Config\Services découvertes pour y chercher une méthode statique dont le nom correspond au service demandé. Ainsi, lorsque ton application appelle service('pdf'), le framework utilise la première classe Services découverte qui déclare une méthode pdf, puis l’appelle.

La découverte est régie par Config\Modules :

$enabled — active ou désactive globalement l’auto-découverte. Par défaut, true.
$discoverInComposer — inclut les packages Composer dans la découverte. Par défaut, true. C’est ce drapeau qui permet au framework de trouver nextpdf/codeigniter.
$composerPackages — un filtre optionnel only / exclude appliqué à l’ensemble des packages Composer.
$aliases — les types d’éléments pris en compte par la découverte. Par défaut, le framework inclut services et registrars, que ce package utilise tous les deux.

La classe fournie par le package est NextPDF\CodeIgniter\Config\Services. Composer mappe le préfixe PSR-4 NextPDF\CodeIgniter\ vers src/CodeIgniter/. Un nom de classe pleinement qualifié doit comporter un namespace de premier niveau (PSR-4 §x1.x2.p5, MUST modal). Le préfixe de namespace est associé au répertoire de base, ce qui permet de résoudre la classe vers son fichier (PSR-4 §x1.x3).

Séquence de démarrage

Autoload Composer. Composer enregistre le mappage PSR-4 et les entrées d’autoload files. Le fichier helper src/CodeIgniter/Helpers/pdf_helper.php est chargé à ce moment-là.
Bootstrap du framework. CodeIgniter lit Config\Modules. Lorsque la découverte est activée, il construit la liste des éléments découverts dans les packages Composer.
Découverte du registrar. Le framework collecte les classes Registrar. Le Registrar::Autoload() du package déclare le helper pdf auprès du chargeur de helpers de CodeIgniter.
Résolution du service au premier appel. Les fabriques de services sont évaluées à la demande. Le premier appel à service('pdf') ou Services::pdf() exécute la fabrique. Les services partagés sont mis en cache dans le locator pendant toute la durée du processus.

Liaisons du conteneur

CodeIgniter 4 n’a pas de conteneur PSR-11. Les « liaisons » correspondent aux méthodes de fabrique statiques de la classe Services. Chaque méthode accepte un paramètre bool $getShared :

Service	Partagé par défaut	Notes
`fontRegistry`	oui	Préchauffé, puis verrouillé.
`imageRegistry`	oui	Cache LRU borné.
`documentFactory`	oui	Sans état.
`pdfDocument`	non	Nouvelle instance à chaque appel.
`pdf`	non	Nouvelle instance à chaque appel.
`tsaClient`	oui	`null` quand il n’y a pas d’URL TSA.
`pdfSigner`	non	`null` quand la signature est désactivée.

Les instances partagées sont conservées dans le cache d’instances BaseService de CodeIgniter pendant toute la durée du processus. L’infrastructure de test du framework vide ce cache via BaseService::reset(), et les tests fonctionnels du package s’appuient sur cette réinitialisation entre les cas.

Ordre de résolution de la configuration

La configuration effective est résolue dans cet ordre :

Les valeurs par défaut du package dans NextPDF\CodeIgniter\Config\NextPdf.
Une classe applicative Config\NextPdf qui étend la classe du package, si elle est présente. CodeIgniter la charge à la place de la configuration par défaut du package.
Les surcharges d’environnement appliquées par BaseConfig, indexées par le nom court de la classe en minuscules nextpdf (clés imbriquées en notation pointée, ou forme de classe pleinement qualifiée).

Le fichier d’extension de configuration de l’application déclare une seule classe et n’exécute aucun effet de bord. Il reste ainsi aligné sur l’attente PSR-1 selon laquelle un fichier doit soit déclarer des symboles, soit exécuter une logique à effets de bord, mais pas les deux (PSR-1 §x1.x1.p3). Le fichier helper en est la contrepartie à effets de bord délibérée. Il déclare les fonctions globales pdf() et pdf_document(), chacune protégée par une vérification function_exists afin qu’un double chargement reste sans danger.

Diagnostics

composer dump-autoload — reconstruis le mappage PSR-4 et la liste d’autoload files après une mise à jour.
Le test de découverte le plus rapide est un contrôleur qui appelle Services::pdfDocument(false) et vérifie qu’un Document est bien renvoyé.
Inspecte vendor/composer/autoload_files.php pour confirmer que le fichier helper est bien enregistré.
Consulte /integrations/codeigniter/troubleshooting/ pour la correspondance entre les échecs et leurs causes.

Conformité

Un nom de classe pleinement qualifié exige un namespace de premier niveau (PSR-4 Autoloader §x1.x2.p5).
Mappage du préfixe de namespace vers le chemin de classe dans le répertoire de base (PSR-4 Autoloader §x1.x3).
Un fichier déclare des symboles ou provoque des effets de bord — la conception du fichier helper (PSR-1 Basic Coding Standard §x1.x1.p3).

Voir aussi

/integrations/codeigniter/integration/ — la référence de câblage et le test de fumée.
/integrations/codeigniter/install/ — installer et vérifier la découverte.
/integrations/codeigniter/overview/ — l’ensemble de la surface de l’API.
/integrations/codeigniter/troubleshooting/ — les modes de défaillance de la découverte.