Riferimento API di CodeIgniter

In breve

Il pacchetto CodeIgniter espone una superficie ridotta, orientata ai controller: un wrapper di libreria Pdf attorno a un singolo documento (Services::pdf() e l’helper globale pdf()), helper per le risposte che trasformano un documento costruito in un DownloadResponse (PdfResponse), le factory di Services sottostanti (registri di font/immagini, factory dei documenti, signer opzionale e client TSA), la classe di configurazione NextPdf e un GeneratePdfJob per la generazione asincrona a partire da callable builder statici.

Punto di partenza: in un controller, chiamare Services::pdf() (o l’helper pdf()), aggiungere contenuto a $pdf->document() e restituire $pdf->download('file.pdf'). Questo percorso unico copre l’attività più comune. Le tabelle di riferimento seguenti sono organizzate per superficie; la sezione Attività comuni presenta per prime le forme eseguibili.

Attività comuni

Di seguito i flussi reali più frequenti. Ogni esempio è verificato sul codice sorgente di nextpdf/codeigniter.

Restituire un PDF scaricabile da un controller — il percorso di rendering canonico:

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

Cosa fa: ottiene un nuovo Pdf che incapsula un nuovo Document, scrive una cella e restituisce un DownloadResponse con disposizione attachment e gli header di sicurezza del pacchetto.

Visualizzare l’anteprima di un PDF inline nel browser — stesso wrapper, inline() al posto di 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');
    }
}

Cosa fa: utilizza l’helper globale pdf() (equivalente a Services::pdf()) e restituisce un DownloadResponse con disposizione inline in modo che il browser visualizzi il PDF anziché scaricarlo.

Generare un PDF in modo asincrono sulla coda — accodare GeneratePdfJob con un builder statico:

<?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],
]);

Cosa fa: accoda la generazione. Il worker convalida il builder (deve essere un callable statico App\PdfBuilders\...::method) e il percorso di output (deve risolversi all’interno di WRITEPATH/pdfs/ e terminare con .pdf), costruisce un nuovo documento e quindi lo salva.

Wrapper di libreria

Consultare questa tabella quando si dispone di un wrapper Pdf e occorrono i suoi metodi di risposta o di salvataggio.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`: nuovo documento core.	Incapsula il documento fornito per una singola operazione di risposta o salvataggio.	`Pdf`	nessuna prevista.	Non riutilizzare il wrapper dopo l’output.
`Pdf::document()`	nessuno.	Restituisce il documento incapsulato.	`NextPDF\Core\Document`	nessuna prevista.	Da utilizzare per chiamare le API di authoring del core.
`Pdf::inline(string $filename = 'document.pdf')`	`filename`: nome file della risposta.	Disposizione inline nel browser.	`CodeIgniter\HTTP\DownloadResponse`	Errori di serializzazione del core.	Delega a `PdfResponse::inline()`.
`Pdf::download(string $filename = 'document.pdf')`	`filename`: nome file della risposta.	Disposizione di tipo attachment nel browser.	`DownloadResponse`	Errori di serializzazione del core.	Delega a `PdfResponse::download()`.
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`: nome file della risposta.	Parità di API con gli altri pacchetti del framework.	`DownloadResponse`	Errori di serializzazione del core.	CodeIgniter gestisce l’output binario in modo nativo.
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`: nome file della risposta.	Parità di API con gli altri pacchetti del framework.	`DownloadResponse`	Errori di serializzazione del core.	Utilizzare gli stessi controlli sulle dimensioni delle risposte non in streaming.
`Pdf::save(string $path)`	`path`: destinazione nel filesystem.	Scrive il documento incapsulato.	`void`	Errori di scrittura del filesystem o del core.	Convalidare le radici di archiviazione prima del salvataggio.

Servizi e helper

Consultare questa tabella quando occorre una factory di servizio specifica o una delle funzioni helper globali e se ne vuole conoscere il comportamento di condivisione e il tipo restituito.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
`Services::fontRegistry(bool $getShared = true)`	`getShared`: flag di servizio condiviso di CodeIgniter.	Registro condiviso, precaricato con i font configurati e quindi bloccato.	`FontRegistryInterface`	`RuntimeException` in caso di estensioni mancanti o percorso dei font non sicuro.	Rifiuta gli stream wrapper e i byte null in `fontsPath`.
`Services::imageRegistry(bool $getShared = true)`	`getShared`: flag di servizio condiviso.	Registro di immagini LRU condiviso e con limite.	`ImageRegistry`	nessuna prevista.	La dimensione della cache è controllata da `imageCacheMb`.
`Services::documentFactory(bool $getShared = true)`	`getShared`: flag di servizio condiviso.	Factory condivisa che utilizza registri condivisi.	`DocumentFactoryInterface`	Errori di configurazione del registro.	La factory è riutilizzabile; i documenti non lo sono.
`Services::tsaClient(bool $getShared = true)`	`getShared`: flag di servizio condiviso.	Restituisce `null` quando `tsa.url` è vuoto.	`TsaClient	null`	Errori del client HTTP o di configurazione TSA.
`Services::pdfSigner(bool $getShared = false)`	`getShared`: flag di servizio condiviso.	Restituisce `null` quando la firma è disabilitata.	`SignerInterface	null`	Errori di certificato o a livello di firma.
`Services::pdfDocument(bool $getShared = false)`	`getShared`: flag di servizio condiviso.	Crea un nuovo documento, applica i valori predefiniti e, facoltativamente, configura PDF/A o Artisan.	`Document`	Errori di estensioni facoltative o di configurazione del documento.	Mantenere il valore predefinito `false` per la sicurezza della richiesta.
`Services::pdf(bool $getShared = false)`	`getShared`: flag di servizio condiviso.	Crea un nuovo wrapper `Pdf` attorno a un nuovo documento.	`NextPDF\CodeIgniter\Libraries\Pdf`	Errori di configurazione del documento.	Servizio principale rivolto ai controller.
`Services::eInvoiceEmbedder()`	nessuno.	Restituisce `null` a meno che non esista la classe embedder per fatture elettroniche di Premium Pro.	`EmbedderInterface	null`	Errori facoltativi di costruzione del pacchetto.
`Services::eInvoiceValidator()`	nessuno.	Restituisce `null` a meno che non esista la classe validator di Premium Enterprise.	`ValidatorInterface	null`	Errori facoltativi di costruzione del pacchetto.
`Services::eInvoiceProfile()`	nessuno.	Restituisce il profilo EN16931 quando Premium Pro è installato.	`ProfileInterface	null`	Errori facoltativi del pacchetto.
`Services::schematronRunner()`	nessuno.	Restituisce `null` a meno che non esista il validator Schematron di Premium Enterprise.	`SchematronRunnerInterface	null`	Errori facoltativi di costruzione del pacchetto.
`Registrar::Autoload()`	nessuno.	Aggiunge l’helper del pacchetto alla configurazione di autoload di CodeIgniter.	`array`	nessuna prevista.	Abilita `pdf()` e `pdf_document()` quando il modulo è caricato.
`pdf()`	nessuno.	Chiama `Services::pdf(false)`.	`Pdf`	Errori di configurazione del documento.	Helper pratico per i controller.
`pdf_document()`	nessuno.	Chiama `Services::pdfDocument(false)`.	`Document`	Errori di configurazione del documento.	Helper pratico quando si preferisce l’API del documento core.

Risposte HTTP

Consultare questa tabella quando si dispone già di un Document costruito e si desidera creare direttamente il DownloadResponse anziché passare attraverso il wrapper Pdf.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: documento costruito; `filename`: nome file della risposta.	Garantisce l’estensione `.pdf` e la disposizione inline.	`DownloadResponse`	Errori di serializzazione del core.	Aggiunge il tipo di contenuto PDF e gli header difensivi.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Uguale a `inline`; la disposizione è di tipo attachment.	Garantisce l’estensione `.pdf`.	`DownloadResponse`	Uguale a `inline`.	Da utilizzare per i download dal browser.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Uguale a `inline`.	Stesso comportamento di `inline` in CI4.	`DownloadResponse`	Uguale a `inline`.	Esiste per la parità di API tra framework diversi.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Uguale a `download`.	Stesso comportamento di `download` in CI4.	`DownloadResponse`	Uguale a `download`.	Esiste per la parità di API tra framework diversi.

Job in coda

Consultare questa tabella quando si configura la generazione asincrona e occorrono le chiavi esatte dei dati del job e il contratto del callable builder.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
`GeneratePdfJob::process()`	Chiavi dei dati del job: `builder`, `outputPath`, facoltativo `context`.	Utilizza un array di contesto vuoto quando omesso.	`void`	`InvalidArgumentException` in caso di builder o percorso di output non sicuro; errori di scrittura del core.	Il builder deve essere `App\PdfBuilders\...\*::method`.
Callable builder	`Document $doc`, `array $context`.	Nessun contesto predefinito oltre ai dati del job.	`Document`	Eccezioni specifiche del builder.	È richiesto un callable statico perché i payload della coda di CI4 sono dati serializzati.

Configurazione

Consultare questa tabella quando si modificano i valori predefiniti — formato pagina, percorsi, firma, TSA o metadati del documento — nella classe di configurazione NextPdf.

Proprietà	Tipo	Comportamento predefinito	Note
`pageFormat`	`string`	`A4`.	Formato pagina predefinito.
`orientation`	`string`	`P`.	Orientamento predefinito.
`unit`	`string`	`mm`.	Unità predefinita.
`pdfa`	`string	null`	`null`.
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` e `WRITEPATH . 'cache/nextpdf'`.	Mantenere i percorsi all’interno dell’archiviazione controllata dall’applicazione.
`signature`	`array`	Disabilitato con livello `B-B`.	Certificato, chiave, password, certificati aggiuntivi e livello.
`tsa`	`array`	Disabilitato quando l’URL è `null`; timeout di 30 secondi.	Credenziali, file mTLS, pin di chiave pubblica e criteri HTTP.
`ocspCache`	`array`	Abilitato con un TTL di 86400 secondi.	Utilizzato dai flussi di convalida della firma quando disponibile.
`preloadFonts`	`list<string>`	Vuoto.	Precaricati prima che il registro venga bloccato.
`imageCacheMb`	`int`	`50`.	Controlla la cache delle immagini per la durata del processo.
`fontCacheLocking`	`bool`	`true`.	Mantiene le mutazioni del registro dei font fuori dalla gestione delle richieste.
`artisan`	`array`	Renderer Chrome disabilitato se non configurato e installato.	Corrisponde a `ChromeRendererConfig::fromArray()`.
`defaults`	`array`	Creator `NextPDF`, author vuoto, lingua `en`, margini e font predefiniti.	`Services::pdfDocument()` applica solo `creator`, `language` e (quando non vuoto) `author`; le chiavi `margin_top`/`right`/`bottom`/`left`, `font_family`, `font_size`, `trim_box` e `bleed_box` sono valori predefiniti definiti che attualmente non vengono applicati.

Note per lo sviluppo

GeneratePdfJob limita l’output a WRITEPATH . 'pdfs' e richiede .pdf.
I callable builder esterni a App\PdfBuilders vengono rifiutati per evitare l’esecuzione di codice arbitrario da payload della coda modificati.
Utilizzare service('pdf') o l’helper del pacchetto per i flussi dei controller; utilizzare i job in coda per la generazione a lunga esecuzione.