Configuración de NextPDF para CodeIgniter 4

De un vistazo

La configuración reside en NextPDF\CodeIgniter\Config\NextPdf, una subclase de BaseConfig de CodeIgniter. Para anular valores, extender la clase en app/Config/ o establecer claves de .env con el prefijo nextpdf.. Los valores predeterminados funcionan sin configuración adicional.

Resumen conceptual

NextPdf es un BaseConfig tipado y, de forma intencional, no es final. La convención de CodeIgniter es que la configuración de la aplicación extienda la clase del paquete, de modo que la aplicación pueda anular los valores predeterminados. Cuando CodeIgniter construye la configuración, BaseConfig resuelve las anulaciones de entorno para cada propiedad pública. Esta resolución también incluye claves de arrays anidados.

Las rutas predeterminadas para fuentes y caché usan la constante WRITEPATH de CodeIgniter: WRITEPATH . 'fonts' y WRITEPATH . 'cache/nextpdf'.

Claves de configuración

Cada clave que aparece a continuación es una propiedad pública de NextPdf. Los valores predeterminados son los valores verificados del código fuente del paquete.

Valores predeterminados de página y documento

Clave	Tipo	Predeterminado	Descripción
pageFormat	string	A4	Formato de página.
orientation	string	P	P para vertical o L para horizontal.
unit	string	mm	Unidad de medida.
defaults.creator	string	NextPDF	Metadatos del creador del PDF.
defaults.author	string	''	Metadatos del autor; se omiten si están vacíos.
defaults.language	string	en	Etiqueta de idioma del documento.
defaults.margin_top	float	10.0	Margen superior.
defaults.margin_right	float	10.0	Margen derecho.
defaults.margin_bottom	float	10.0	Margen inferior.
defaults.margin_left	float	10.0	Margen izquierdo.
defaults.font_family	string	dejavusans	Familia de fuentes predeterminada.
defaults.font_size	float	12.0	Tamaño de fuente predeterminado.
defaults.trim_box	list<float>|null	null	Trim box, si se establece.
defaults.bleed_box	list<float>|null	null	Bleed box, si se establece.

El paquete aplica defaults.creator y defaults.language a cada documento. Aplica defaults.author solo cuando ese valor es no está vacío.

Rutas y cachés

Clave	Tipo	Predeterminado	Descripción
fontsPath	string	WRITEPATH/fonts	Directorio de archivos de fuentes.
cachePath	string	WRITEPATH/cache/nextpdf	Directorio de la caché.
preloadFonts	list<string>	[]	Rutas absolutas de fuentes que se precargan al arranque.
imageCacheMb	int	50	Presupuesto de la caché LRU de imágenes en MB.
fontCacheLocking	bool	true	Bloquea la caché de fuentes después del precalentamiento.

El registro de fuentes rechaza una fontsPath que contenga un wrapper de stream (://) o un byte nulo. Ese rechazo genera un error de tiempo de ejecución. Consulta /integrations/codeigniter/security-and-operations/.

Archivado y color (NextPDF Pro)

Clave	Tipo	Predeterminado	Descripción
pdfa	string|null	null	Versión de PDF/A: 4, 4e, 4f.
iccProfile.rgb	string|null	null	Ruta del perfil ICC RGB.
iccProfile.cmyk	string|null	null	Ruta del perfil ICC CMYK.

pdfa surte efecto solo cuando NextPDF Pro está instalado y la capacidad de archivado está disponible. Con solo el núcleo instalado, la clave se ignora.

Firma digital (NextPDF Pro / Enterprise)

Clave	Tipo	Predeterminado	Descripción
signature.enabled	bool	false	Habilita el servicio de firma.
signature.certificate	string|null	null	Ruta del archivo de certificado.
signature.private_key	string|null	null	Ruta del archivo de clave privada.
signature.password	string	''	Contraseña de la clave privada.
signature.extra_certs	list<string>	[]	Rutas de certificados adicionales para la cadena.
signature.level	string	B-B	Identificador del nivel de firma.

Services::pdfSigner() devuelve null a menos que signature.enabled sea true y signature.certificate no esté vacío. El nivel predeterminado es B-B. NextPDF Pro proporciona la firma de referencia B-B. Los niveles de validación a largo plazo pertenecen a una capacidad independiente de Enterprise. Se documentan en la referencia Premium, no aquí.

PAdES B-T lo genera el motor Core. La integración con CodeIgniter no agrega B-T por sí misma y Pro entrega únicamente la firma de referencia B-B. Esta documentación se actualizará si Pro B-T llega a publicarse y en el momento en que eso ocurra.

Autoridad de sellado de tiempo

Clave	Tipo	Predeterminado	Descripción
tsa.url	string|null	null	URL del endpoint de la TSA.
tsa.username	string	''	Nombre de usuario para la autenticación básica de la TSA.
tsa.password	string	''	Contraseña para la autenticación básica de la TSA.
tsa.cert	string|null	null	Ruta del certificado de cliente.
tsa.key	string|null	null	Ruta de la clave de cliente.
tsa.timeout	int	30	Tiempo de espera de la solicitud en segundos.
tsa.pinned_public_keys	list<string>	[]	Claves públicas fijadas de la TSA.
tsa.warn_on_key_rotation	bool	true	Advertir sobre la rotación de claves de la TSA.
tsa.allow_insecure_http	bool	false	Permitir HTTP en texto plano hacia la TSA.

Services::tsaClient() devuelve null cuando tsa.url es null o una cadena vacía. Cuando se selecciona un nivel de firma que requiere un sello de tiempo, el firmante adjunta el cliente de la TSA automáticamente.

Caché de OCSP

Clave	Tipo	Predeterminado	Descripción
ocspCache.enabled	bool	true	Habilita la caché de respuestas OCSP.
ocspCache.ttl	int	86400	TTL de la caché en segundos.
ocspCache.directory	string|null	null	Directorio de la caché; valor predeterminado del motor cuando el valor es null.

Renderer HTML de Chrome (NextPDF Artisan)

Clave	Tipo	Predeterminado	Descripción
artisan.chrome_binary	string|null	null	Ruta del binario de Chrome/Chromium.
artisan.render_timeout	int	30	Tiempo de espera de renderizado en segundos.
artisan.default_css	string	''	Hoja de estilos predeterminada.
artisan.no_sandbox	bool	false	Pasar --no-sandbox a Chrome.
artisan.max_html_size	int	5000000	Tamaño máximo del HTML de entrada en bytes.

El renderer de Chrome se configura en el documento solo cuando artisan.chrome_binary está establecido y nextpdf/artisan está instalado.

Anular con .env

BaseConfig resuelve las anulaciones de entorno por propiedad. La clave de búsqueda es el nombre corto de la clase en minúsculas, nextpdf, seguido de la ruta de la propiedad. Las claves de arrays anidados se indican con puntos. Se aceptan tanto la forma con puntos como la forma con guiones bajos.

.env

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

El prefijo es el nombre corto de la clase en minúsculas. Sigue siendo nextpdf aunque la clase se escriba NextPdf. También se acepta la forma totalmente cualificada (NextPDF\CodeIgniter\Config\NextPdf.fontsPath).

Anular extendiendo la clase

Para mantener una configuración tipada y bajo control de versiones, extender la clase del paquete en app/Config/. CodeIgniter carga la clase de la aplicación en lugar de la predeterminada del paquete. Este archivo declara una clase y no provoca efectos secundarios. Así se mantiene alineado con la expectativa de PSR-1 de que un archivo o bien declara símbolos o bien ejecuta lógica con efectos secundarios, pero no ambas cosas (PSR-1 §x1.x1.p3).

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

Casos límite y puntos delicados

• Anular una sola clave anidada con .env anula únicamente esa clave; el resto del array conserva su valor predeterminado.
• .env almacena valores como cadenas. CodeIgniter convierte true/false y las cadenas numéricas. Entrecomilla los valores que deban permanecer como cadenas literales.
• Extender la clase con un array defaults parcial reemplaza todo el array. Incluye cada clave, como se muestra arriba.

Notas de seguridad

Mantener las rutas de los certificados y las claves fuera del control de versiones. Proporcionarlas a través de .env o de un gestor de secretos. tsa.allow_insecure_http debe permanecer en false en producción. Consulta /integrations/codeigniter/security-and-operations/.

Conformidad

• El archivo de extensión de la configuración de la aplicación declara una sola clase y ningún efecto secundario (PSR-1 §x1.x1.p3).

Contexto comercial

El núcleo de NextPDF es Apache-2.0. Las claves signature.* y pdfa surten efecto solo cuando NextPDF Pro o Enterprise está instalado. El paquete de CodeIgniter expone los métodos de servicio correspondientes. Esos métodos devuelven null hasta que se instala el paquete Premium correspondiente. Consultar </get-license/?intent=codeigniter-signing>.

Consulta también

• /integrations/codeigniter/install/ — instala el paquete.
• /integrations/codeigniter/quickstart/ — primer PDF.
• /integrations/codeigniter/production-usage/ — controladores y trabajos de cola conectados mediante DI.
• /integrations/codeigniter/security-and-operations/ — endurecimiento de la configuración de firma y rutas.