CodeIgniter API reference

At a glance

The CodeIgniter package exposes a small controller-facing application programming interface (API). It includes a Pdf library wrapper for one document (Services::pdf() and the global pdf() helper), response helpers that turn a built document into a DownloadResponse (PdfResponse), the Services factories behind them (font and image registries, the document factory, and optional signer and time-stamping authority (TSA) client), the NextPdf configuration class, and GeneratePdfJob for asynchronous generation from static builder callables.

Start with the main controller path: call Services::pdf() (or the pdf() helper), add content to $pdf->document(), and return $pdf->download('file.pdf'). That path covers the common case. The reference tables are organized by surface; Common tasks shows the runnable shapes first.

Common tasks

These are the most common production flows. Each sample is source-verified against nextpdf/codeigniter.

Use the canonical render path to return a downloadable Portable Document Format (PDF) file from a controller:

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

What it does: resolves a fresh Pdf around a fresh Document, writes one cell, and returns a DownloadResponse with attachment disposition and the package security headers.

Preview a PDF inline in the browser with the same wrapper and inline() instead of 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');
    }
}

What it does: uses the global pdf() helper (equivalent to Services::pdf()) and returns a DownloadResponse with inline disposition so the browser displays the PDF instead of downloading it.

Generate a PDF asynchronously on the queue with GeneratePdfJob and a static builder:

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

What it does: enqueues generation. The worker validates the builder (must be an App\PdfBuilders\...::method static callable) and the output path (must resolve under WRITEPATH/pdfs/ and end in .pdf), builds a fresh document, and saves it.

Library wrapper

Use this table when you have a Pdf wrapper and need its response or save methods.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`: fresh core document.	Wraps the supplied document for one response or save operation.	`Pdf`	None expected.	Do not reuse the wrapper after output.
`Pdf::document()`	none.	Returns the wrapped document.	`NextPDF\Core\Document`	None expected.	Use this to call core authoring APIs.
`Pdf::inline(string $filename = 'document.pdf')`	`filename`: response filename.	Uses browser inline disposition.	`CodeIgniter\HTTP\DownloadResponse`	Core serialization errors.	Delegates to `PdfResponse::inline()`.
`Pdf::download(string $filename = 'document.pdf')`	`filename`: response filename.	Uses browser attachment disposition.	`DownloadResponse`	Core serialization errors.	Delegates to `PdfResponse::download()`.
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`: response filename.	Provides API parity with other framework packages.	`DownloadResponse`	Core serialization errors.	CodeIgniter handles binary output natively.
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`: response filename.	Provides API parity with other framework packages.	`DownloadResponse`	Core serialization errors.	Use the same size controls as non-streamed responses.
`Pdf::save(string $path)`	`path`: filesystem target.	Writes the wrapped document.	`void`	Filesystem or core write errors.	Validate storage roots before saving.

Services and helpers

Use this table when you need a specific service factory or global helper function, including its sharing behavior and return type.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`Services::fontRegistry(bool $getShared = true)`	`getShared`: CodeIgniter shared-service flag.	Returns a shared registry, warms it with configured fonts, then locks it.	`FontRegistryInterface`	`RuntimeException` for missing extensions or unsafe font path.	Rejects stream wrappers and null bytes in `fontsPath`.
`Services::imageRegistry(bool $getShared = true)`	`getShared`: shared-service flag.	Returns a shared bounded least recently used (LRU) image registry.	`ImageRegistry`	None expected.	Cache size is controlled by `imageCacheMb`.
`Services::documentFactory(bool $getShared = true)`	`getShared`: shared-service flag.	Returns a shared factory that uses shared registries.	`DocumentFactoryInterface`	Registry setup errors.	The factory is reusable; documents are not.
`Services::tsaClient(bool $getShared = true)`	`getShared`: shared-service flag.	Returns `null` when `tsa.url` is empty.	`TsaClient	null`	Hypertext Transfer Protocol (HTTP) client or TSA configuration errors.
`Services::pdfSigner(bool $getShared = false)`	`getShared`: shared-service flag.	Returns `null` when signing is disabled.	`SignerInterface	null`	Certificate or signature-level errors.
`Services::pdfDocument(bool $getShared = false)`	`getShared`: shared-service flag.	Creates a fresh document, applies defaults, and optionally configures PDF/A or Artisan.	`Document`	Optional extension or document configuration errors.	Keep the default `false` for request safety.
`Services::pdf(bool $getShared = false)`	`getShared`: shared-service flag.	Creates a fresh `Pdf` wrapper around a fresh document.	`NextPDF\CodeIgniter\Libraries\Pdf`	Document setup errors.	Main controller-facing service.
`Services::eInvoiceEmbedder()`	none.	Returns `null` unless the Premium Pro e-invoice embedder class exists.	`EmbedderInterface	null`	Optional package construction errors.
`Services::eInvoiceValidator()`	none.	Returns `null` unless the Premium Enterprise validator class exists.	`ValidatorInterface	null`	Optional package construction errors.
`Services::eInvoiceProfile()`	none.	Returns the EN16931 profile when Premium Pro is installed.	`ProfileInterface	null`	Optional package errors.
`Services::schematronRunner()`	none.	Returns `null` unless the Premium Enterprise Schematron validator exists.	`SchematronRunnerInterface	null`	Optional package construction errors.
`Registrar::Autoload()`	none.	Adds the package helper to CodeIgniter autoload configuration.	`array`	None expected.	Enables `pdf()` and `pdf_document()` when the module is loaded.
`pdf()`	none.	Calls `Services::pdf(false)`.	`Pdf`	Document setup errors.	Convenience helper for controllers.
`pdf_document()`	none.	Calls `Services::pdfDocument(false)`.	`Document`	Document setup errors.	Convenience helper when the core document API is preferred.

HTTP responses

Use this table when you already have a built Document and want to construct the DownloadResponse yourself instead of using the Pdf wrapper.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: built document; `filename`: response filename.	Ensures the `.pdf` extension and inline disposition.	`DownloadResponse`	Core serialization errors.	Adds the PDF content type and defensive headers.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Same as `inline`; disposition is attachment.	Ensures `.pdf` extension.	`DownloadResponse`	Same as `inline`.	Use for browser downloads.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Same as `inline`.	Same behavior as `inline` in CodeIgniter 4 (CI4).	`DownloadResponse`	Same as `inline`.	Exists for cross-framework API parity.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Same as `download`.	Same behavior as `download` in CI4.	`DownloadResponse`	Same as `download`.	Exists for cross-framework API parity.

Queue job

Use this table when you wire asynchronous generation and need the exact job data keys and builder-callable contract.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`GeneratePdfJob::process()`	Job data keys: `builder`, `outputPath`, and optional `context`.	Uses an empty context array when omitted.	`void`	`InvalidArgumentException` for unsafe builder or output path; core write errors.	Builder must be `App\PdfBuilders\...\*::method`.
Builder callable	`Document $doc`, `array $context`.	No default context beyond job data.	`Document`	Builder-specific exceptions.	Requires a static callable because CI4 queue payloads are serialized data.

Configuration

Use this table when you change defaults for page format, paths, signing, TSA, or document metadata on the NextPdf config class.

Property	Type	Default behavior	Notes
`pageFormat`	`string`	`A4`.	Sets the default page format.
`orientation`	`string`	`P`.	Sets the default orientation.
`unit`	`string`	`mm`.	Sets the default unit.
`pdfa`	`string	null`	`null`.
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` and `WRITEPATH . 'cache/nextpdf'`.	Keep paths inside application-controlled storage.
`signature`	`array`	Disabled with level `B-B`.	Certificate, key, password, extra certificates, and level.
`tsa`	`array`	Disabled when the Uniform Resource Locator (URL) is `null`; timeout 30 seconds.	Credentials, mutual Transport Layer Security (mTLS) files, public-key pins, and HTTP policy.
`ocspCache`	`array`	Enabled with a time to live (TTL) of 86400 seconds.	Used by signature validation flows when available.
`preloadFonts`	`list<string>`	Empty.	Warmed before the registry is locked.
`imageCacheMb`	`int`	`50`.	Controls the process-lifetime image cache.
`fontCacheLocking`	`bool`	`true`.	Keeps font registry mutations out of request handling.
`artisan`	`array`	Chrome renderer disabled unless configured and installed.	Maps to `ChromeRendererConfig::fromArray()`.
`defaults`	`array`	Creator `NextPDF`, empty author, language `en`, default margins, and default font.	`Services::pdfDocument()` applies only `creator`, `language`, and (when non-empty) `author`; `margin_top`/`right`/`bottom`/`left`, `font_family`, `font_size`, `trim_box`, and `bleed_box` are defined defaults, but it does not currently apply them.

Development notes

GeneratePdfJob confines output to WRITEPATH . 'pdfs' and requires .pdf.
Builder callables outside App\PdfBuilders are rejected to avoid arbitrary code execution from modified queue payloads.
Use service('pdf') or the package helper for controller flows; use queue jobs for long-running generation.