NextPDF CodeIgniter boot and discovery

At a glance

CodeIgniter 4 discovers the package’s Services class, helper functions, and registrar through Composer package discovery. This page explains the sequence and the configuration that controls it.

How CodeIgniter Services discovery works

CodeIgniter 4 resolves a service by scanning each discovered Config\Services class for a static method that matches the requested service name. When your application calls service('pdf'), the framework finds the first discovered Services class that declares a pdf method, and then calls it.

Discovery is governed by Config\Modules:

$enabled — primary switch for auto-discovery. Default true.
$discoverInComposer — extends discovery to Composer packages. Default true. This flag lets the framework find nextpdf/codeigniter.
$composerPackages — an optional only / exclude filter for the Composer package set.
$aliases — the element types that participate in discovery. The framework default includes services and registrars, and this package uses both.

The package class is NextPDF\CodeIgniter\Config\Services. Composer maps the PHP Standards Recommendation 4 (PSR-4) prefix NextPDF\CodeIgniter\ to src/CodeIgniter/. A fully qualified class name must have a top-level namespace (PSR-4 §x1.x2.p5, modal MUST). The namespace prefix maps to the base directory, so the class resolves to its file (PSR-4 §x1.x3).

Boot sequence

Composer autoload. Composer registers the PSR-4 map and the files autoload entries. It loads the helper file src/CodeIgniter/Helpers/pdf_helper.php at this point.
Framework bootstrap. CodeIgniter reads Config\Modules. When discovery is enabled, it builds the discovered element list across Composer packages.
Registrar discovery. The framework collects Registrar classes. The package’s Registrar::Autoload() advertises the pdf helper to CodeIgniter’s helper loader.
Service resolution on first call. Service factories are lazy. The first call to service('pdf') or Services::pdf() runs the factory. Shared services are cached on the locator for the process.

Container bindings

CodeIgniter 4 does not provide a PSR-11 container. Instead, the static factory methods on the Services class act as the bindings. Each method accepts a bool $getShared parameter:

Service	Shared by default	Notes
`fontRegistry`	yes	Warmed, then locked.
`imageRegistry`	yes	Bounded least recently used (LRU) cache.
`documentFactory`	yes	Stateless.
`pdfDocument`	no	Fresh per call.
`pdf`	no	Fresh per call.
`tsaClient`	yes	`null` when no Time-Stamp Authority (TSA) URL is configured.
`pdfSigner`	no	`null` when signing is disabled.

Shared instances live in CodeIgniter’s BaseService instance cache for the process. The framework test harness clears that cache with BaseService::reset(), and the package functional tests rely on that reset between cases.

Configuration resolution order

The effective configuration resolves in this order:

Package defaults in NextPDF\CodeIgniter\Config\NextPdf.
An application class Config\NextPdf that extends the package class, when present. CodeIgniter loads it instead of the package default.
Environment overrides applied by BaseConfig, keyed by the lowercase short class name nextpdf (dotted nested keys, or the fully qualified class form).

The application config-extension file declares one class and has no side effects. That keeps it aligned with the PSR-1 expectation that a file either declares symbols or runs side-effecting logic, but not both (PSR-1 §x1.x1.p3). The helper file is the deliberate side-effecting counterpart. It declares the global pdf() and pdf_document() functions, and each one is guarded by a function_exists check so a double load is safe.

Diagnostics

composer dump-autoload — rebuilds the PSR-4 map and the files autoload list after an upgrade.
To probe discovery quickly, use a controller that calls Services::pdfDocument(false) and asserts a Document return.
Inspect vendor/composer/autoload_files.php to confirm that the helper file is registered.
See /integrations/codeigniter/troubleshooting/ for the failure-to-cause mapping.

Conformance

Fully qualified class name requires a top-level namespace (PSR-4 Autoloader §x1.x2.p5).
Namespace prefix to base directory class-path mapping (PSR-4 Autoloader §x1.x3).
A file declares symbols or causes side effects — the helper file design (PSR-1 Basic Coding Standard §x1.x1.p3).