NextPDF voor CodeIgniter 4

In een oogopslag

nextpdf/codeigniter verbindt de NextPDF Portable Document Format (PDF)-engine met een CodeIgniter 4-applicatie via de Services-laag van het framework. Je bouwt PDF-documenten in controllers, jobs of commands en geeft ze vervolgens terug als native CodeIgniter Hypertext Transfer Protocol (HTTP)-responses.

Installatie

composer require nextpdf/codeigniter

De composer.json van het pakket vereist php >=8.4 <9.0, nextpdf/core ^3.0 || ^5.2 en codeigniter4/framework ^4.6. Het raadt daarnaast nextpdf/artisan, nextpdf/premium en codeigniter4/queue aan. Zie /integrations/codeigniter/install/ voor de volledige tabel met vereisten, optionele pakketten en verificatiestappen.

Conceptueel overzicht

NextPDF is een PHP 8.4 PDF 2.0-engine. De core-engine (nextpdf/core) is framework-onafhankelijk. Hij weet niets van HTTP, routing of dependency-wiring. nextpdf/codeigniter is de adapter die de engine met een CodeIgniter 4-applicatie verbindt. Zodra de adapter staat, hoef je registries, factories of responseverwerking niet zelf te bedraden.

Het pakket voegt vier dingen toe aan een CodeIgniter 4-applicatie:

• Een Services-klasse (NextPDF\CodeIgniter\Config\Services) die CodeIgniter automatisch ontdekt. Hij stelt benoemde services beschikbaar: fontRegistry, imageRegistry, documentFactory, pdfDocument, pdf, tsaClient en pdfSigner.
• Een Pdf-library (NextPDF\CodeIgniter\Libraries\Pdf) — een high-level application programming interface (API) voor controllers. Hij omhult een wegwerpdocument en zet het in één aanroep om naar een response.
• Een PdfResponse-helper (NextPDF\CodeIgniter\Http\PdfResponse) die een CodeIgniter DownloadResponse maakt voor inline-preview of download. Hij voegt een vaste set response-hardening-headers toe.
• Twee globale helperfuncties, pdf() en pdf_document(). Ze worden geregistreerd via de Composer-files-autoload-entry en de Registrar van het pakket.

Het pakket detecteert ook optionele NextPDF-extensies wanneer het een document bouwt. Als nextpdf/artisan geïnstalleerd is en er een Chrome-binary geconfigureerd is, krijgt het document de Chrome-renderer. Als NextPDF Pro geïnstalleerd is, zijn PDF/A-uitvoer en digitale ondertekening beschikbaar via hetzelfde Services-oppervlak. Detectie is voorwaardelijk en verloopt stil. Het pakket vereist nooit een extensie die niet aanwezig is.

Waarom een Services-klasse en geen container-binding

CodeIgniter 4 levert geen PSR-11-dependency-injection-container. In plaats daarvan gebruikt het een Services-locator. Een Services-locator is een door het framework ontdekte klasse met statische factorymethoden. Elke methode geeft ofwel een gedeelde instantie ofwel een nieuwe terug. PSR-11 ontmoedigt het service-locatorpatroon — waarbij een container in een object wordt doorgegeven zodat het object zijn eigen dependencies kan ophalen — in PSR-11 §1.3 met het modale werkwoord SHOULD NOT. Het pakket volgt de locatorconventie van CodeIgniter. Het houdt het locatoroppervlak ook minimaal en expliciet: elke service is een benoemde factorymethode met een bool $getShared-parameter, en aanroepers ontvangen concrete objecten in plaats van een container-handle.

Dit ontwerp houdt de CodeIgniter-integratie consistent met de Laravel- en Symfony-integraties. Elke integratie stelt dezelfde logische services beschikbaar via het idioom van zijn eigen framework.

API-oppervlak

Toegangspunt	Type	Geeft terug	Levensduur
Services::fontRegistry()	service	FontRegistryInterface	gedeeld (opgewarmd, daarna vergrendeld)
Services::imageRegistry()	service	ImageRegistry	gedeeld (begrensde least recently used (LRU)-cache)
Services::documentFactory()	service	DocumentFactoryInterface	gedeeld (stateless)
Services::pdfDocument(false)	service	NextPDF\Core\Document	nieuw per aanroep
Services::pdf(false)	service	NextPDF\CodeIgniter\Libraries\Pdf	nieuw per aanroep
Services::tsaClient()	service	?TsaClient	gedeeld; null wanneer er geen timestamp authority (TSA)-URL is
Services::pdfSigner(false)	service	?SignerInterface	nieuw; null wanneer ondertekening uitgeschakeld is
pdf()	helper	Pdf	nieuw per aanroep
pdf_document()	helper	Document	nieuw per aanroep
PdfResponse::inline() / download()	statisch	DownloadResponse	per aanroep
GeneratePdfJob	queue-job	—	één per dispatch

Codevoorbeeld — Quick start

Een controller geeft een PDF in drie regels terug. Services::pdf() geeft een nieuwe Pdf-library terug die een nieuw document omhult. download() maakt vervolgens een CodeIgniter DownloadResponse.

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

De volledige uitvoerbare walkthrough staat in /integrations/codeigniter/quickstart/. Daarin komen routing, inline-preview en de helpervarianten pdf() en pdf_document() aan bod.

Codevoorbeeld — Productie

Vraag in productie een niet-gedeelde instantie aan met Services::pdf(false). Vang de ene basisexceptie op, NextPDF\Exception\NextPdfException; elke core- en extensiefout is hiervan afgeleid. Log de fout met context en slik hem niet in.

try {
    $pdf = Services::pdf(false);
    $pdf->document()->addPage();
    $pdf->document()->cell(0, 10, "Invoice #{$id}");

    return $pdf->download("invoice-{$id}.pdf");
} catch (NextPdfException $e) {
    $logger->error('pdf.invoice.failed', [
        'invoice_id' => $id,
        'exception' => $e::class,
        'message' => $e->getMessage(),
    ]);

    return $this->response
        ->setStatusCode(ResponseInterface::HTTP_INTERNAL_SERVER_ERROR)
        ->setJSON(['error' => 'pdf_generation_failed', 'invoice_id' => $id]);
}

De volledige productiecontroller staat in /integrations/codeigniter/production-usage/. Die voegt observability-timing, worker-veilige levensduren en asynchrone generatie toe.

Randgevallen en valkuilen

• De font- en image-registries zijn singletons met proceslevensduur. Een document wordt nooit gedeeld. pdfDocument en pdf geven bij elke aanroep een nieuwe instantie terug, zodat de ene aanvraag geen inhoud naar een andere kan laten lekken. Services::pdf(false) en pdf() geven beide een nieuwe library terug die een nieuw document omhult.
• Het pakket vereist de PHP-extensies mbstring en zlib. De font-registry valideert ze één keer per proces. Als een van beide extensies ontbreekt, werpt de font-registry een runtimefout die de ontbrekende extensie noemt.
• Het gedrag van optionele extensies hangt af van wat er in dezelfde applicatie geïnstalleerd is. Als alleen nextpdf/core aanwezig is, geven de ondertekenings- en PDF/A-paden null terug of worden ze overgeslagen. Ze falen nooit met een expliciete foutmelding.

Prestaties

De integratie voegt geen meetbare overhead toe bovenop de engine zelf. De font-registry wordt één keer geparseerd en daarna vergrendeld. De image-registry is een LRU-cache die begrensd wordt door de imageCacheMb-instelling (standaard 50 MB). De core-engine en de documentinhoud bepalen de kosten voor het bouwen van de PDF, niet de adapter. Het budget per pagina voor deze documentatieset is 1500 ms wall / 128 MB piek. Echte recipes stellen in de front-matter hun eigen budget in.

Beveiligingsnotities

PdfResponse voegt een vaste set responseheaders toe aan elke PDF die hij uitstuurt: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy: default-src 'none', X-Robots-Tag: noindex, nofollow en Referrer-Policy: no-referrer. Bestandsnamen worden gesaneerd en niet-ASCII-namen worden uitgestuurd met een Request for Comments (RFC) 5987-extended-parameter. De queue-job beperkt builder-callables tot de namespace App\PdfBuilders en uitvoerpaden tot WRITEPATH/pdfs/. Zie /integrations/codeigniter/security-and-operations/ voor het volledige dreigingsmodel.

Conformiteit

• Moduledetectie steunt op PSR-4-autoloading van Composer. Een namespaceprefix wordt toegewezen aan een basismap, en de volledig gekwalificeerde klassenaam wordt toegewezen aan een bestandspad (PSR-4 §x1.x3).
• Het Services-ontwerp volgt de locatorrichtlijn die besproken wordt onder PSR-11 §1.3.

Commerciële context

NextPDF core is Apache-2.0. Digitale handtekeningen, PDF/A-archivering en Factur-X-e-factuurinbedding worden geleverd door NextPDF Pro en NextPDF Enterprise. Het CodeIgniter-pakket stelt de bijbehorende servicemethoden beschikbaar. Die methoden geven null terug totdat het bijbehorende Premium-pakket in dezelfde applicatie geïnstalleerd is.

Zie ook

• /integrations/codeigniter/install/ — installeer en verifieer het pakket.
• /integrations/codeigniter/quickstart/ — je eerste PDF in een controller.
• /integrations/codeigniter/configuration/ — alle configuratiesleutels.
• /integrations/codeigniter/boot-and-discovery/ — hoe CodeIgniter de Services-klasse vindt.
• /integrations/codeigniter/integration/ — bedradingsreferentie en smoketest.