Referencia de la API de CodeIgniter

De un vistazo

El paquete de CodeIgniter expone una superficie pequeña y orientada a controladores: un wrapper de biblioteca Pdf que encapsula un documento (Services::pdf() y el helper global pdf()), helpers de respuesta que convierten un documento ya construido en un DownloadResponse (PdfResponse), las factories de Services que respaldan esa superficie (registros de fuentes/imágenes, factory de documentos, signer opcional y cliente TSA), la clase de configuración NextPdf y un GeneratePdfJob para generación asíncrona a partir de callables estáticos de builder.

Punto de partida: en un controlador, llamar a Services::pdf() (o al helper pdf()), añadir contenido a $pdf->document() y devolver $pdf->download('file.pdf'). Esa ruta única cubre la tarea más común. Las tablas de referencia siguientes están organizadas por superficie; la sección Tareas comunes muestra primero las formas ejecutables.

Tareas comunes

Estos son los flujos reales más frecuentes. Cada ejemplo está verificado contra el código fuente de nextpdf/codeigniter.

Devolver un PDF descargable desde un controlador: la ruta de renderizado canónica:

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

Qué hace: obtiene un Pdf nuevo que envuelve un Document nuevo, escribe una celda y devuelve un DownloadResponse con disposición attachment y las cabeceras de seguridad del paquete.

Previsualizar un PDF en línea en el navegador: el mismo wrapper, con inline() en lugar de 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');
    }
}

Qué hace: usa el helper global pdf() (equivalente a Services::pdf()) y devuelve un DownloadResponse con disposición inline para que el navegador muestre el PDF en lugar de descargarlo.

Generar un PDF de forma asíncrona en la cola: encolar GeneratePdfJob con un builder estático:

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

Qué hace: pone la generación en la cola. El worker valida el builder (debe ser un callable estático App\PdfBuilders\...::method) y la ruta de salida (debe resolverse dentro de WRITEPATH/pdfs/ y terminar en .pdf), construye un documento nuevo y después lo guarda.

Wrapper de la biblioteca

Consultar esta tabla cuando se tenga un wrapper Pdf y se necesiten sus métodos de respuesta o guardado.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`: documento nuevo del núcleo.	Envuelve el documento suministrado para una operación de respuesta o guardado.	`Pdf`	No se espera ninguna.	No reutilizar el wrapper después de la salida.
`Pdf::document()`	ninguno.	Devuelve el documento envuelto.	`NextPDF\Core\Document`	No se espera ninguna.	Se usa para llamar a las APIs de autoría del núcleo.
`Pdf::inline(string $filename = 'document.pdf')`	`filename`: nombre de archivo de la respuesta.	Disposición inline en el navegador.	`CodeIgniter\HTTP\DownloadResponse`	Errores de serialización del núcleo.	Delega en `PdfResponse::inline()`.
`Pdf::download(string $filename = 'document.pdf')`	`filename`: nombre de archivo de la respuesta.	Disposición attachment en el navegador.	`DownloadResponse`	Errores de serialización del núcleo.	Delega en `PdfResponse::download()`.
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`: nombre de archivo de la respuesta.	Paridad de API con otros paquetes de framework.	`DownloadResponse`	Errores de serialización del núcleo.	CodeIgniter gestiona la salida binaria de forma nativa.
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`: nombre de archivo de la respuesta.	Paridad de API con otros paquetes de framework.	`DownloadResponse`	Errores de serialización del núcleo.	Aplica los mismos controles de tamaño que las respuestas no transmitidas en streaming.
`Pdf::save(string $path)`	`path`: destino en el sistema de archivos.	Escribe el documento envuelto.	`void`	Errores de escritura del sistema de archivos o del núcleo.	Validar las raíces de almacenamiento antes de guardar.

Servicios y helpers

Consultar esta tabla cuando se necesite una factory de servicio específica o una de las funciones helper globales, y se quiera conocer su modo de compartición y su tipo de retorno.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`Services::fontRegistry(bool $getShared = true)`	`getShared`: flag de servicio compartido de CodeIgniter.	Registro compartido, precargado con las fuentes configuradas y luego bloqueado.	`FontRegistryInterface`	`RuntimeException` por extensiones ausentes o por una ruta de fuentes insegura.	Rechaza los wrappers de stream y los bytes nulos en `fontsPath`.
`Services::imageRegistry(bool $getShared = true)`	`getShared`: flag de servicio compartido.	Registro de imágenes LRU acotado y compartido.	`ImageRegistry`	ninguna esperada.	El tamaño de la caché lo controla `imageCacheMb`.
`Services::documentFactory(bool $getShared = true)`	`getShared`: flag de servicio compartido.	Factory compartida que usa registros compartidos.	`DocumentFactoryInterface`	Errores de configuración del registro.	La factory es reutilizable; los documentos no.
`Services::tsaClient(bool $getShared = true)`	`getShared`: flag de servicio compartido.	Devuelve `null` cuando `tsa.url` está vacío.	`TsaClient	null`	Errores del cliente HTTP o de configuración de TSA.
`Services::pdfSigner(bool $getShared = false)`	`getShared`: flag de servicio compartido.	Devuelve `null` cuando la firma está deshabilitada.	`SignerInterface	null`	Errores de certificado o de firma.
`Services::pdfDocument(bool $getShared = false)`	`getShared`: flag de servicio compartido.	Crea un documento nuevo, aplica los valores predeterminados y configura opcionalmente PDF/A o Artisan.	`Document`	Errores opcionales de extensión o de configuración del documento.	Mantener el valor predeterminado `false` por seguridad de la solicitud.
`Services::pdf(bool $getShared = false)`	`getShared`: flag de servicio compartido.	Crea un wrapper `Pdf` nuevo alrededor de un documento nuevo.	`NextPDF\CodeIgniter\Libraries\Pdf`	Errores de configuración del documento.	Servicio principal orientado al controlador.
`Services::eInvoiceEmbedder()`	ninguno.	Devuelve `null` a menos que exista la clase del embedder de e-invoice de Premium Pro.	`EmbedderInterface	null`	Errores opcionales de construcción del paquete.
`Services::eInvoiceValidator()`	ninguno.	Devuelve `null` a menos que exista la clase del validador de Premium Enterprise.	`ValidatorInterface	null`	Errores opcionales de construcción del paquete.
`Services::eInvoiceProfile()`	ninguno.	Devuelve el perfil EN16931 cuando Premium Pro está instalado.	`ProfileInterface	null`	Errores opcionales del paquete.
`Services::schematronRunner()`	ninguno.	Devuelve `null` a menos que exista el validador Schematron de Premium Enterprise.	`SchematronRunnerInterface	null`	Errores opcionales de construcción del paquete.
`Registrar::Autoload()`	ninguno.	Añade el helper del paquete a la configuración de autoload de CodeIgniter.	`array`	ninguna esperada.	Habilita `pdf()` y `pdf_document()` cuando el módulo está cargado.
`pdf()`	ninguno.	Llama a `Services::pdf(false)`.	`Pdf`	Errores de configuración del documento.	Helper de conveniencia para controladores.
`pdf_document()`	ninguno.	Llama a `Services::pdfDocument(false)`.	`Document`	Errores de configuración del documento.	Helper de conveniencia cuando se prefiere la API de documentos del núcleo.

Respuestas HTTP

Consultar esta tabla cuando ya se tenga un Document construido y se quiera construir manualmente el DownloadResponse en lugar de pasar por el wrapper Pdf.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: documento construido; `filename`: nombre de archivo de la respuesta.	Garantiza la extensión `.pdf` y la disposición inline.	`DownloadResponse`	Errores de serialización del núcleo.	Añade el tipo de contenido PDF y cabeceras defensivas.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Igual que `inline`; la disposición es attachment.	Garantiza la extensión `.pdf`.	`DownloadResponse`	Igual que `inline`.	Usar para descargas del navegador.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Igual que `inline`.	Mismo comportamiento que `inline` en CI4.	`DownloadResponse`	Igual que `inline`.	Existe para la paridad de API entre frameworks.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Igual que `download`.	Mismo comportamiento que `download` en CI4.	`DownloadResponse`	Igual que `download`.	Existe para la paridad de API entre frameworks.

Job de la cola

Consultar esta tabla cuando se conecte la generación asíncrona y se necesiten las claves exactas de los datos del job y el contrato del callable de builder.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`GeneratePdfJob::process()`	Claves de los datos del job: `builder`, `outputPath` y `context` opcional.	Usa un array de contexto vacío cuando se omite.	`void`	`InvalidArgumentException` por un builder o una ruta de salida inseguros; errores de escritura del núcleo.	El builder debe ser `App\PdfBuilders\...\*::method`.
Callable de builder	`Document $doc`, `array $context`.	Sin contexto predeterminado más allá de los datos del job.	`Document`	Excepciones específicas del builder.	Se requiere un callable estático porque las cargas útiles de la cola de CI4 son datos serializados.

Configuración

Consultar esta tabla cuando se cambien los valores predeterminados (formato de página, rutas, firma, TSA o metadatos del documento) en la clase de configuración NextPdf.

Propiedad	Tipo	Comportamiento predeterminado	Notas
`pageFormat`	`string`	`A4`.	Formato de página predeterminado.
`orientation`	`string`	`P`.	Orientación predeterminada.
`unit`	`string`	`mm`.	Unidad predeterminada.
`pdfa`	`string	null`	`null`.
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` y `WRITEPATH . 'cache/nextpdf'`.	Mantener las rutas dentro del almacenamiento controlado por la aplicación.
`signature`	`array`	Deshabilitada con el nivel `B-B`.	Certificado, clave, contraseña, certificados adicionales y nivel.
`tsa`	`array`	Deshabilitado cuando la URL es `null`; tiempo de espera de 30 segundos.	Credenciales, archivos mTLS, pins de clave pública y política HTTP.
`ocspCache`	`array`	Habilitada con un TTL de 86400 segundos.	La usan los flujos de validación de firmas cuando está disponible.
`preloadFonts`	`list<string>`	Vacía.	Precargadas antes de que se bloquee el registro.
`imageCacheMb`	`int`	`50`.	Controla la caché de imágenes durante la vida del proceso.
`fontCacheLocking`	`bool`	`true`.	Mantiene las mutaciones del registro de fuentes fuera de la gestión de la solicitud.
`artisan`	`array`	El renderer de Chrome está deshabilitado a menos que esté configurado e instalado.	Se asigna a `ChromeRendererConfig::fromArray()`.
`defaults`	`array`	Creator `NextPDF`, autor vacío, idioma `en`, márgenes y fuente predeterminados.	`Services::pdfDocument()` aplica solo `creator`, `language` y (cuando no está vacío) `author`; las claves `margin_top`/`right`/`bottom`/`left`, `font_family`, `font_size`, `trim_box` y `bleed_box` son valores predeterminados definidos, pero actualmente no se aplican.

Notas de desarrollo

GeneratePdfJob confina la salida a WRITEPATH . 'pdfs' y requiere .pdf.
Los callables de builder fuera de App\PdfBuilders se rechazan para evitar la ejecución de código arbitrario desde cargas útiles de la cola modificadas.
Usar service('pdf') o el helper del paquete para los flujos desde controladores; usar jobs de la cola para la generación de larga duración.