Integrazione di NextPDF in CodeIgniter

In sintesi

Per integrare il pacchetto è sufficiente installarlo: CodeIgniter 4 lo rileva automaticamente. Questa pagina è il riferimento per l’integrazione. Descrive la discovery, il modello dei binding, la pubblicazione della configurazione e uno smoke test basato su un singolo metodo che dimostra il funzionamento dell’integrazione.

Installazione

composer require nextpdf/codeigniter

Non occorre modificare un service provider né intervenire su un file di bootstrap. Per i vincoli di versione verificati, consultare /integrations/codeigniter/install/.

Boot / auto-discovery

CodeIgniter 4 individua il pacchetto tramite la package discovery di Composer. Questo avviene quando Config\Modules::$discoverInComposer è true, il valore predefinito del framework. Il prefisso PSR-4 NextPDF\CodeIgniter\ è mappato su src/CodeIgniter/. Grazie a questa mappatura, il framework risolve NextPDF\CodeIgniter\Config\Services al relativo file (PSR-4 §x1.x3). /integrations/codeigniter/boot-and-discovery/ documenta la sequenza completa e le proprietà di Config\Modules che la governano.

Binding del container

CodeIgniter 4 non include alcun container PSR-11. PSR-11 §1.3 sconsiglia il pattern service-locator (modale SHOULD NOT). Il pacchetto segue la convenzione del locator del framework, mantenendola però minimale. Ogni binding è esposto come factory statica nominata, con un parametro bool $getShared.

Nome del servizio	Restituisce	Ciclo di vita predefinito
fontRegistry	FontRegistryInterface	condiviso
imageRegistry	ImageRegistry	condiviso
documentFactory	DocumentFactoryInterface	condiviso
pdfDocument	Document	nuovo
pdf	Pdf	nuovo
tsaClient	?TsaClient	condiviso
pdfSigner	?SignerInterface	nuovo

La risoluzione può passare da uno qualsiasi dei due entry point: sono equivalenti.

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Config\Services;

$a = Services::pdf(false);   // direct
$b = \service('pdf');        // helper → Services::pdf()

Gli helper globali pdf() e pdf_document() sono semplici wrapper di Services::pdf(false) e Services::pdfDocument(false).

Pubblicare la configurazione

La configurazione del pacchetto risiede in NextPDF\CodeIgniter\Config\NextPdf, una classe BaseConfig non final. Per eseguirne l’override sono supportate due modalità:

1. Estendere la classe (tipizzata, sotto controllo di versione). Creare app/Config/NextPdf.php:

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;
}

CodeIgniter carica la classe dell’applicazione al posto di quella predefinita del pacchetto.

2. Eseguire l’override con .env (per ambiente). Il prefisso è il nome breve della classe in minuscolo, nextpdf:

nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem

/integrations/codeigniter/configuration/ documenta ogni chiave e la regola di override degli array.

Smoke test di service provider / bundle

CodeIgniter non prevede alcun service provider o classe bundle da testare. Lo smoke test equivalente verifica invece due aspetti: che la discovery abbia risolto i servizi e che i cicli di vita si comportino come specificato. Il test riportato di seguito è un’azione eseguibile di controller che riproduce le asserzioni funzionali del pacchetto stesso.

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\ResponseInterface;
use NextPDF\CodeIgniter\Config\Services;
use NextPDF\CodeIgniter\Libraries\Pdf;
use NextPDF\Core\Document;

final class NextPdfSmokeController extends BaseController
{
    public function check(): ResponseInterface
    {
        // Discovery resolved the services.
        $document = Services::pdfDocument(false);
        $library = Services::pdf(false);

        // Documents are fresh per call (no cross-request leakage).
        $freshIsolated = Services::pdfDocument(false) !== $document;

        // Registries are shared singletons.
        $registrySingleton = Services::fontRegistry() === Services::fontRegistry();

        // Optional services degrade to null without Premium / TSA config.
        $signerOptional = Services::pdfSigner(false) === null;

        $ok = $document instanceof Document
            && $library instanceof Pdf
            && $freshIsolated
            && $registrySingleton
            && $signerOptional;

        return $this->response
            ->setStatusCode($ok ? 200 : 500)
            ->setJSON([
                'discovery' => $document instanceof Document,
                'document_fresh_per_call' => $freshIsolated,
                'registry_shared' => $registrySingleton,
                'signer_optional_null' => $signerOptional,
            ]);
    }
}

Associare una rotta a questa azione ed eseguire la richiesta. Una risposta 200 con tutti i flag impostati a true dimostra il corretto funzionamento dell’integrazione. Ogni asserzione presente qui corrisponde a un comportamento verificato nella suite di test funzionali del pacchetto.

Casi limite e insidie

• Se l’applicazione host disabilita la discovery di Composer, aggiungere nextpdf/codeigniter a Config\Modules::$composerPackages['only'].
• Services::pdfDocument(true) restituisce un documento condiviso. Esiste esclusivamente per il reset nei test. Non richiedere mai il documento condiviso nel codice delle richieste o nei job.
• Services::pdfSigner() e Services::tsaClient() restituiscono null finché non vengono configurate la firma o un URL TSA. Si tratta di una graceful degradation prevista, non di un errore.

Conformità

• Mappatura classe-percorso per la discovery dei moduli (PSR-4 Autoloader §x1.x3).
• Indicazioni sul service-locator per il modello dei binding (PSR-11 Container §1.3).

Contesto commerciale

Il core di NextPDF è Apache-2.0. I servizi Pro ed Enterprise, una volta installati, sono esposti sulla stessa superficie Services. Il pacchetto CodeIgniter espone i metodi di servizio corrispondenti. Ciascuno restituisce null finché non viene installato il pacchetto Premium corrispondente. Vedere </get-license/?intent=codeigniter>.

Vedere anche

• /integrations/codeigniter/boot-and-discovery/ — funzionamento interno della discovery.
• /integrations/codeigniter/install/ — vincoli di versione e verifica.
• /integrations/codeigniter/quickstart/ — primo PDF.
• /integrations/codeigniter/production-usage/ — controller integrati tramite DI e il job di coda.
• /integrations/codeigniter/configuration/ — ogni chiave di configurazione.