NextPDF per CodeIgniter: avvio e individuazione

In breve

CodeIgniter 4 individua automaticamente la classe Services del pacchetto, le funzioni helper e il registrar tramite il meccanismo di individuazione dei pacchetti Composer. Questa pagina descrive la sequenza esatta e la configurazione che la governa.

Come funziona l’individuazione dei servizi in CodeIgniter

CodeIgniter 4 risolve un servizio esaminando ogni classe Config\Services individuata per cercare un metodo statico con lo stesso nome del servizio richiesto. Di conseguenza, quando l’applicazione chiama service('pdf'), il framework seleziona la prima classe Services individuata che dichiara un metodo pdf e lo invoca.

L’individuazione è regolata da Config\Modules:

• $enabled — controllo principale dell’individuazione automatica. Valore predefinito true.
• $discoverInComposer — estende l’individuazione ai pacchetti Composer. Valore predefinito true. È questo flag che consente al framework di individuare nextpdf/codeigniter.
• $composerPackages — un filtro facoltativo only / exclude sull’insieme dei pacchetti Composer.
• $aliases — i tipi di elementi che partecipano all’individuazione. L’impostazione predefinita del framework include services e registrars, entrambi utilizzati da questo pacchetto.

La classe del pacchetto è NextPDF\CodeIgniter\Config\Services. Composer associa il prefisso PSR-4 NextPDF\CodeIgniter\ a src/CodeIgniter/. Un nome di classe completo deve includere un namespace di primo livello (PSR-4 §x1.x2.p5, modale MUST). Il prefisso del namespace è associato alla directory di base, quindi la classe viene risolta nel file corrispondente (PSR-4 §x1.x3).

Sequenza di avvio

1. Autoload di Composer. Composer registra la mappa PSR-4 e le voci di autoload files. Il file helper src/CodeIgniter/Helpers/pdf_helper.php viene caricato in questa fase.
2. Bootstrap del framework. CodeIgniter legge Config\Modules. Se l’individuazione è abilitata, costruisce l’elenco degli elementi individuati nei pacchetti Composer.
3. Individuazione dei registrar. Il framework raccoglie le classi Registrar. Il metodo Registrar::Autoload() del pacchetto segnala l’helper pdf al caricatore di helper di CodeIgniter.
4. Risoluzione del servizio alla prima chiamata. Le factory dei servizi sono lazy. La prima chiamata a service('pdf') o Services::pdf() esegue la factory. I servizi condivisi vengono memorizzati nella cache del locator per la durata del processo.

Binding del container

In CodeIgniter 4 non è disponibile un container PSR-11. I «binding» corrispondono ai metodi factory statici della classe Services. Ogni metodo accetta un parametro bool $getShared:

Servizio	Condiviso per impostazione predefinita	Note
fontRegistry	sì	Preinizializzato, quindi bloccato.
imageRegistry	sì	Cache LRU con limite.
documentFactory	sì	Stateless.
pdfDocument	no	Nuova istanza a ogni chiamata.
pdf	no	Nuova istanza a ogni chiamata.
tsaClient	sì	null in assenza di un URL TSA.
pdfSigner	no	null quando la firma è disabilitata.

Le istanze condivise risiedono nella cache delle istanze BaseService di CodeIgniter per la durata del processo. L’harness di test del framework svuota tale cache tramite BaseService::reset() e i test funzionali del pacchetto fanno affidamento su questo reset tra un caso e l’altro.

Ordine di risoluzione della configurazione

La configurazione effettiva viene risolta in questo ordine:

1. Valori predefiniti del pacchetto in NextPDF\CodeIgniter\Config\NextPdf.
2. Una classe dell’applicazione Config\NextPdf che estende la classe del pacchetto, se presente. CodeIgniter la carica al posto dell’impostazione predefinita del pacchetto.
3. Override d’ambiente applicati da BaseConfig, indicizzati in base al nome breve della classe in minuscolo nextpdf (chiavi annidate con notazione a punti oppure nella forma di classe completa).

Il file di estensione della configurazione dell’applicazione dichiara una sola classe e non produce effetti collaterali. Questo lo allinea al principio di PSR-1 secondo cui un file deve dichiarare simboli oppure eseguire logica con effetti collaterali, ma non entrambe le cose (PSR-1 §x1.x1.p3). Il file helper è, deliberatamente, la controparte con effetti collaterali. Dichiara le funzioni globali pdf() e pdf_document() e ciascuna è protetta da un controllo function_exists, in modo che un doppio caricamento sia sicuro.

Diagnostica

• composer dump-autoload — ricostruisce la mappa PSR-4 e l’elenco di autoload files dopo un aggiornamento.
• Il test più rapido per verificare l’individuazione consiste in un controller che chiama Services::pdfDocument(false) e verifica la restituzione di un Document.
• Esaminare vendor/composer/autoload_files.php per verificare che il file helper sia registrato.
• Vedere /integrations/codeigniter/troubleshooting/ per la mappatura tra errori e cause.

Conformità

• Un nome di classe completo richiede un namespace di primo livello (PSR-4 Autoloader §x1.x2.p5).
• Mappatura del percorso della classe dal prefisso del namespace alla directory di base (PSR-4 Autoloader §x1.x3).
• Un file dichiara simboli oppure produce effetti collaterali — il design del file helper (PSR-1 Basic Coding Standard §x1.x1.p3).

Vedere anche

• /integrations/codeigniter/integration/ — il riferimento di configurazione e lo smoke test.
• /integrations/codeigniter/install/ — installazione e verifica dell’individuazione.
• /integrations/codeigniter/overview/ — l’intera superficie dell’API.
• /integrations/codeigniter/troubleshooting/ — modalità di errore dell’individuazione.