Guida per sviluppatori CodeIgniter

In sintesi

Il pacchetto CodeIgniter espone factory di servizio, funzioni di supporto e un piccolo wrapper di libreria Pdf per un singolo documento. Il wrapper è pratico nei controller. L’elaborazione in coda usa builder callable statici perché i payload delle code di CodeIgniter sono dati serializzati.

Usare questa guida per progettare flussi di controller, servizi, builder di coda o test attorno a nextpdf/codeigniter.

Confine architetturale

Livello	Di proprietà di	Responsabilità	Da non collocare qui
Controller	Applicazione	Autorizzare, richiamare un builder o un servizio, restituire un `DownloadResponse`.	Logica di layout condivisa.
Wrapper di libreria	`nextpdf/codeigniter`	Incapsulare un singolo `Document` e fornire helper response/save.	Archiviazione di documenti a lunga durata.
Factory di servizio	`nextpdf/codeigniter`	Creare registry condivisi e nuovi documenti.	Radici di archiviazione specifiche per l’azienda.
Builder di coda	Applicazione	Costruire un documento a partire da un input callable statico.	Oggetti request o stato non serializzabile.
Motore principale	`nextpdf/nextpdf`	Costruire e serializzare il PDF.	Policy di risposta o di coda CodeIgniter.

Ciclo di vita a runtime

Fase	Comportamento	Azione dello sviluppatore
Registrazione dell’autoload	`Registrar::Autoload()` registra il caricamento degli helper per il modulo.	Caricare il modulo tramite la configurazione di CodeIgniter.
Risoluzione del servizio	`Services::pdf()` restituisce per impostazione predefinita un wrapper per un nuovo documento.	Risolverlo una sola volta per richiesta.
Creazione	Il codice applicativo usa `Pdf::document()` per chiamare il documento principale.	Mantenere il codice di costruzione del documento nei servizi o nei builder.
Risposta	`PdfResponse` restituisce un `DownloadResponse`.	Lasciare che il pacchetto imposti gli header PDF.
Esecuzione in coda	`GeneratePdfJob::process()` convalida il builder e il percorso di output, quindi salva il documento.	Collocare i builder di coda sotto `App\PdfBuilders`.

Struttura dell’applicazione consigliata

Percorso	Scopo
`app/PdfBuilders/*`	Builder statici e sicuri per le code, accettati da `GeneratePdfJob`.
`app/Libraries/*`	Wrapper applicativi opzionali per workflow documentali ricorrenti.
`app/Services/*`	Recupero dei dati di dominio e policy di archiviazione.
`app/Config/NextPdf.php`	Override applicativi per la configurazione del pacchetto.
`tests/app/PdfBuilders/*`	Test dei builder e dei payload di coda.

Usare gli helper del pacchetto per i flussi brevi. Usare chiamate di servizio esplicite quando la costruzione del documento appartiene a una classe da testare direttamente.

<?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');
    }
}

Pattern del builder di coda

I builder di coda dovrebbero essere statici, deterministici e collocati sotto App\PdfBuilders. Mantenere l’array di contesto abbastanza semplice da poter essere serializzato e verificato.

<?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;
    }
}

Il job limita l’output alla directory PDF configurata dell’applicazione. Se l’applicazione necessita di archiviazione specifica per tenant, collocare tale policy in un unico servizio e testarla prima dell’invio in coda.

Punti di estensione

Punto di estensione	Da usare per	Vincolo
`Services::pdfDocument()`	Personalizzazione della creazione del documento.	Deve restituire un nuovo documento.
`Services::fontRegistry()`	Warm-up dei font e accesso al registry.	Rifiutare i percorsi non sicuri e mantenere il registry bloccato dopo il warm-up.
`Services::pdfSigner()`	Firma digitale opzionale.	Restituisce `null` quando la firma è disabilitata.
`NextPDF\CodeIgniter\Libraries\Pdf`	Wrapper destinato ai controller.	Un wrapper corrisponde a un singolo documento.
`App\PdfBuilders::*`	Builder di documenti sicuri per le code.	È richiesta una stringa callable statica.
`app/Config/NextPdf.php`	Impostazioni predefinite dell’applicazione e parametri di integrazione.	Mantenere espliciti i valori di produzione.

Flusso di lavoro di sviluppo

Iniziare con un controller che richiama pdf() o service('pdf').
Spostare la costruzione ricorrente dei documenti in app/PdfBuilders o in un servizio dell’applicazione.
Usare GeneratePdfJob quando la generazione è troppo lenta per il percorso della richiesta.
Mantenere il contesto della coda serializzabile e di dimensioni ridotte.
Archiviare l’output sotto la radice di archiviazione PDF approvata, a meno che non si estenda deliberatamente la policy.
Aggiungere test per helper, servizi, payload di coda e percorsi non sicuri.

Gestione degli errori

Errore	Dove dovrebbe essere gestito	Risposta consigliata
Estensione mancante o percorso di font non sicuro	Factory di servizio.	Fallire rapidamente durante la risoluzione del servizio.
Builder callable non valido	Convalida del job di coda.	Rifiutare il job e registrare la stringa del builder senza segreti.
Percorso di output non sicuro	Servizio di archiviazione e job di coda.	Rifiutare prima dell’invio e mantenere la convalida del job.
Errore di serializzazione della risposta	Gestione degli errori del controller o del framework.	Non inviare un corpo di risposta parziale.
Classe Premium opzionale non disponibile	Valore restituito dal metodo di servizio.	Gestire `null` esplicitamente prima di usare le funzionalità opzionali di fatturazione elettronica.

Impostazioni predefinite sicure

Aspetto	Predefinito	Quando eseguire l’override
Namespace del builder di coda	`App\PdfBuilders`.	Mantenere il valore predefinito a meno che non si aggiorni anche la policy di sicurezza.
Radice di output	`WRITEPATH/pdfs`.	Eseguire l’override solo con una allowlist più restrittiva.
Nome del file di risposta	`document.pdf`.	Usare nomi di file aziendali sanificati.
Metodi di streaming	Parità di API con altri framework.	Non fare affidamento sullo streaming come meccanismo di limitazione della memoria in CodeIgniter.
Servizio documento	Nuovo per impostazione predefinita.	Non richiedere documenti condivisi nel codice della richiesta.

Elenco di controllo per i test

I test dei servizi verificano che ogni risoluzione di Services::pdf() restituisca un documento indipendente.
I test degli helper verificano che pdf() e pdf_document() restituiscano nuovi oggetti.
I test di risposta verificano gli header e la normalizzazione del nome del file.
I test di coda coprono stringhe di builder non valide e percorsi di output non sicuri.
I test dei builder vengono eseguiti con dati di contesto rappresentativi.
I test di configurazione coprono il percorso dei font, il percorso della cache, la firma disabilitata e gli stati con TSA disabilitato.