CodeIgniter developer guide

At a glance

The CodeIgniter package provides service factories, helper functions, and a small Pdf library wrapper for a single Portable Document Format (PDF) document. Use the wrapper in controllers. Queue work uses static builder callables because CodeIgniter queue payloads must be serialized data.

Use this guide to design controller flows, services, queue builders, and tests around nextpdf/codeigniter.

Architecture boundary

Layer	Owned by	Responsibility	Do not put here
Controller	Application	Authorize, call a builder or service, and return a DownloadResponse.	Shared layout logic.
Library wrapper	nextpdf/codeigniter	Wrap one Document and provide response and save helpers.	Long-lived document storage.
Service factory	nextpdf/codeigniter	Create shared registries and fresh documents.	Business-specific storage roots.
Queue builder	Application	Build a document from static callable input.	Request objects or state that cannot be serialized.
Core engine	nextpdf/nextpdf	Build and serialize the PDF.	CodeIgniter response or queue policy.

Runtime lifecycle

Stage	Behavior	Developer action
Autoload registration	Registrar::Autoload() registers helper loading for the module.	Load the module through CodeIgniter configuration.
Service resolution	Services::pdf() returns a wrapper around a fresh document by default.	Resolve once per request.
Authoring	Application code uses Pdf::document() for core document calls.	Keep document-building code in services or builders.
Response	PdfResponse returns a DownloadResponse.	Let the package set PDF headers.
Queue execution	GeneratePdfJob::process() validates builder and output path, then saves.	Put queue builders under App\PdfBuilders.

Recommended application structure

Path	Purpose
app/PdfBuilders/*	Static queue-safe builders accepted by GeneratePdfJob.
app/Libraries/*	Optional application wrappers around repeated document workflows.
app/Services/*	Domain data retrieval and storage policy.
app/Config/NextPdf.php	Application overrides for package config.
tests/app/PdfBuilders/*	Builder and queue payload tests.

Use package helpers for short flows. Use explicit service calls when document construction belongs in a class you can test directly.

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

Queue builder pattern

Queue builders should be static, deterministic, and located under App\PdfBuilders. Keep the context array simple enough to serialize and audit.

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

The job confines output to the configured application PDF directory. If your application needs tenant-specific storage, put that policy in one service, and test it before dispatching the job.

Extension points

Extension point	Use it for	Constraint
Services::pdfDocument()	Customize document creation.	Must return a fresh document.
Services::fontRegistry()	Warm up fonts and access the registry.	Reject unsafe paths, and keep the registry locked after warmup.
Services::pdfSigner()	Enable optional digital signing.	Return null when signing is disabled.
NextPDF\CodeIgniter\Libraries\Pdf	Wrap controller-facing document work.	One wrapper maps to one document.
App\PdfBuilders::*	Queue-safe document builders.	Static callable string required.
app/Config/NextPdf.php	Application defaults and integration settings.	Keep production values explicit.

Development workflow

1. Start with a controller that calls pdf() or service('pdf').
2. Move repeated document construction into app/PdfBuilders or an application service.
3. Use GeneratePdfJob when generation is too slow for the request path.
4. Keep queue context serializable and small.
5. Store output under the approved PDF storage root unless you deliberately extend the policy.
6. Add tests for helpers, services, queue payloads, and unsafe paths.

Failure handling

Failure	Where it should be handled	Recommended response
Missing extension or unsafe font path	Service factory.	Fail fast during service resolution.
Invalid builder callable	Queue job validation.	Reject the job and log the builder string without secrets.
Unsafe output path	Storage service and queue job.	Reject before dispatch, and keep job validation.
Response serialization error	Controller or framework error handling.	Do not send a partial response body.
Optional Premium class unavailable	Service method return value.	Handle null explicitly before using optional e-invoice features.

Safe defaults

Concern	Default	When to override
Queue builder namespace	App\PdfBuilders.	Keep default unless you also update the security policy.
Output root	WRITEPATH/pdfs.	Override only with a stronger allowlist.
Response filename	document.pdf.	Use sanitized business filenames.
Stream methods	Application programming interface (API) parity with other frameworks.	Do not rely on streaming as a memory boundary in CodeIgniter.
Document service	Fresh by default.	Do not request shared documents from request code.

Testing checklist

• Service tests verify each Services::pdf() resolution returns an independent document.
• Helper tests verify pdf() and pdf_document() return fresh objects.
• Response tests verify headers and filename normalization.
• Queue tests cover invalid builder strings and unsafe output paths.
• Builder tests use representative context data.
• Config tests cover font path, cache path, signing disabled, and Time-Stamp Authority (TSA) disabled states.