Configuración del paquete NextPDF para Laravel

De un vistazo

config/nextpdf.php se publica con php artisan vendor:publish --tag=nextpdf-config. Cada clave cuenta con una variable de entorno de respaldo y un valor predeterminado fijo en el código. Esta página documenta cada clave exactamente como aparece en el config/nextpdf.php del paquete.

Instalación

php artisan vendor:publish --tag=nextpdf-config

El proveedor también fusiona los valores predeterminados del paquete bajo la clave de configuración nextpdf durante register(). Por lo tanto, las claves no definidas vuelven a los valores siguientes incluso antes de publicar la configuración.

Visión conceptual

La mayoría de las variables de entorno aceptan un nombre NEXTPDF_* o un nombre heredado TCPDF_*. El prefijo heredado se admite durante el período de transición documentado en UPGRADE.md; los despliegues nuevos deben usar la forma NEXTPDF_*. El archivo de configuración resuelve los valores en este orden: variable de entorno → valor del archivo publicado → valor predeterminado del paquete.

Superficie de la API — claves de configuración

Disposición del documento

Clave	Variable de entorno (principal)	Predeterminado	Efecto
page_format	NEXTPDF_PAGE_FORMAT	A4	Formato de página predeterminado (A4, A3, A5, Letter, Legal, Tabloid)
orientation	NEXTPDF_ORIENTATION	P	Orientación vertical (P) u horizontal (L)
unit	NEXTPDF_UNIT	mm	Unidad de medida (pt, mm, cm, in)
defaults.creator	NEXTPDF_CREATOR	NextPDF	Metadatos del creador del documento; se aplican en el enlace PdfDocumentInterface correspondiente
defaults.author	NEXTPDF_AUTHOR	(vacío)	Metadatos del autor; se aplican solo cuando no están vacíos
defaults.language	NEXTPDF_LANG	en	Idioma del documento; se aplica en el enlace del documento
defaults.margin_top / _right / _bottom / _left	—	10	Márgenes predeterminados
defaults.font_family	—	dejavusans	Familia tipográfica predeterminada
defaults.font_size	—	12	Tamaño de fuente predeterminado
defaults.trim_box	—	null	TrimBox [left, bottom, right, top] en puntos, o null
defaults.bleed_box	—	null	BleedBox [left, bottom, right, top] en puntos, o null

El proveedor aplica defaults.creator, defaults.language y (cuando está definido) defaults.author a cada documento que se acaba de resolver. La rama defaults.author se omite cuando el valor está vacío.

Archivado y color

Clave	Variable de entorno (principal)	Predeterminado	Efecto
pdfa	NEXTPDF_PDFA	null	Nivel de archivado PDF/A (null, 4, 4e, 4f). Un valor distinto de null habilita PDF/A en el enlace del documento y requiere nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	Directorio para fuentes TrueType adicionales; se incorpora a la ruta de búsqueda del registro de fuentes
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	Directorio de caché para fuentes analizadas y archivos temporales
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	Ruta del perfil ICC RGB; obligatoria para PDF/A
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	Perfil ICC CMYK opcional para flujos de trabajo de impresión
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	Usa flock en la caché de fuentes para evitar la corrupción cuando varios workers de cola escriben de forma concurrente

Asignar a pdfa un valor distinto de null requiere la edición Premium. Sin nextpdf/premium, resolver el enlace del documento con pdfa definido genera un error de clase no encontrada para el tipo de versión PDF/A. Esta página no describe el comportamiento de archivado de Premium; consultar la documentación de Premium.

Memoria del worker (entornos de ejecución de larga vida)

Clave	Variable de entorno (principal)	Predeterminado	Efecto
preload_fonts	—	[]	Lista de rutas absolutas de archivos de fuentes analizadas al arrancar el worker. El registro de fuentes se bloquea después del precalentamiento
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	Presupuesto de la caché de imágenes LRU en MB. 0 desactiva la caché. El proveedor no impone ningún límite superior

El presupuesto de la caché de imágenes no tiene un límite superior impuesto por el proveedor. Para acotarlo, aplicar un límite de memoria del contenedor o php.inimemory_limit. El archivo de configuración recomienda un máximo práctico de 256 MB.

Firma digital (Premium)

Clave	Variable de entorno (principal)	Predeterminado	Efecto
signature.enabled	NEXTPDF_SIGN_ENABLED	false	Cuando es false (o el certificado está vacío), SignerInterface se resuelve como null
signature.certificate	NEXTPDF_SIGN_CERT	null	Ruta del certificado de firma
signature.private_key	NEXTPDF_SIGN_KEY	null	Ruta de la clave privada
signature.password	NEXTPDF_SIGN_PASSWORD	(vacío)	Frase de paso de la clave
signature.extra_certs	—	[]	Rutas de los certificados de CA intermedias
signature.level	NEXTPDF_SIGN_LEVEL	B-B	Nivel base PAdES que se pasa al firmante

El paquete Core documentado aquí no incluye una implementación concreta del firmante; el enlace SignerInterface se resuelve como null hasta que nextpdf/premium proporcione un firmante. Con Premium, level: B-B produce una firma de nivel base PAdES B-B. Los niveles base PAdES superiores dependen de una autoridad de sellado de tiempo configurada y de las capacidades de Premium; esta página no documenta esos niveles.

Autoridad de sellado de tiempo

Clave	Variable de entorno (principal)	Predeterminado	Efecto
tsa.url	NEXTPDF_TSA_URL	null	Endpoint de la TSA. Cuando está vacío, TsaClient se resuelve como null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(vacío)	Credenciales HTTP de la TSA
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	Certificado / clave de cliente para mTLS hacia la TSA
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	Tiempo de espera HTTP en segundos para el cliente PSR-18
tsa.pinned_public_keys	—	[]	Pins SPKI SHA-256 en Base64 (RFC 7469). Vacío desactiva el pinning
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	Emite una advertencia cuando la TSA presenta una SPKI sin pin configurado
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	Permite HTTP en texto plano hacia la TSA. Mantener en false en producción

Caché de respuestas OCSP

Clave	Variable de entorno (principal)	Predeterminado	Efecto
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	Almacena en caché las respuestas de OCSP durante la validación
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	TTL de la caché en segundos
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	Directorio de la caché; null mantiene la caché solo en memoria

Cola

Clave	Variable de entorno (principal)	Predeterminado	Efecto
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	Conexión de la cola; null usa la conexión predeterminada
queue.queue	NEXTPDF_QUEUE_NAME	pdf	Nombre de la cola a la que GeneratePdfJob envía sus trabajos
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	Tiempo de espera por trabajo en segundos

Renderizador CDP de Chrome (extensión Artisan)

Clave	Variable de entorno (principal)	Predeterminado	Efecto
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	valor de la variable de entorno o sin definir	Ruta al binario de Chrome/Chromium
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	Tiempo de espera de renderizado en segundos
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(vacío)	CSS predeterminado que se inyecta en el HTML renderizado
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	Desactiva el sandbox de Chrome
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	Tamaño máximo de la entrada HTML en bytes

La sección artisan se aplica al enlace del documento solo cuando está presente una clase factory del navegador Chrome (la extensión nextpdf/artisan). Cuando está ausente, la sección se ignora.

Ejemplo de código — Producción

resource: config/nextpdf.php (subset, verified against the published file)

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

Casos límite y trampas

• signature.enabled = true con un signature.certificate vacío sigue haciendo que SignerInterface se resuelva como null; ambos deben estar definidos.
• tsa.url = null fuerza TsaClient a null, incluso si otras claves tsa.* están pobladas.
• signature.level = null se revierte a PAdES B-B en el firmante.
• image_cache_mb establecido en null (no en 0) vuelve al valor predeterminado de 50 MB; 0 desactiva explícitamente la caché.
• Las variables de entorno heredadas TCPDF_* siguen siendo legibles, pero están obsoletas; migra a NEXTPDF_*.

Rendimiento

La lectura de la configuración es un acceso a un array de O(1). Con preload_fonts, se asume un análisis único de O(f) al arrancar el worker a cambio de menor latencia en la primera solicitud. Un image_cache_mb mayor reduce la decodificación repetida de imágenes a costa de memoria residente en el proceso.

Notas de seguridad

tsa.allow_insecure_http debilita la confianza en el sellado de tiempo y debe permanecer en false en producción. Las URL de la TSA deben proceder únicamente de una configuración de confianza; si se exponen a través de una superficie de administración, aplicar un firewall de salida o una política de DNS para mitigar la falsificación de solicitudes. Consultar /integrations/laravel/security-and-operations/.

Conformidad

Ningún estándar normativo rige la forma del archivo de configuración; todas las claves se verifican contra el config/nextpdf.php del paquete en la revisión documentada. La semántica del nivel de firma depende de Premium y queda fuera del alcance de esta página de Core.

Contexto comercial

Las secciones signature y tsa activan la firma de Premium cuando nextpdf/premium está instalado. Es una capacidad opcional de Enterprise; el paquete Core documentado aquí no necesita ningún cambio de código para adoptarla. Consultar https://nextpdf.dev/get-license/?intent=laravel-signing.

Véase también

• /integrations/laravel/install/ — publicar el archivo de configuración
• /integrations/laravel/production-usage/ — configuración aplicada en un controlador real
• /integrations/laravel/security-and-operations/ — endurecer la TSA y los ajustes de la cola
• /integrations/laravel/boot-and-discovery/ — qué enlace activa cada clave