Solución de problemas de NextPDF en CodeIgniter 4

De un vistazo

Cada síntoma que aparece a continuación apunta a una causa verificada en el código fuente del paquete o del framework. Cada uno incluye también una solución concreta.

Descubrimiento y resolución

`Services::pdfDocument()` devuelve `null`

Para resolver un servicio, CodeIgniter examina las clases Config\Services descubiertas en busca de un método coincidente. Un valor de retorno null significa que el framework nunca descubrió la clase Services del paquete.

Las causas y sus soluciones:

El descubrimiento automático está desactivado. La aplicación anfitriona puede establecer Config\Modules::$discoverInComposer = false. Si es así, agregar nextpdf/codeigniter a $composerPackages['only']. El descubrimiento examina los paquetes de Composer solo cuando esta marca está en true.
El autoloader está desactualizado. Composer asigna el prefijo de namespace NextPDF\CodeIgniter\ a su directorio base. Un classmap desactualizado oculta la clase (PSR-4 §x1.x3). Ejecutar composer dump-autoload.
La lista $aliases se recortó. El descubrimiento se ejecuta solo para las entradas de Config\Modules::$aliases. El paquete necesita services y también registrars para los helpers. Restaurar ambas entradas.

`pdf()` o `pdf_document()` no está definida

Los helpers se registran por dos rutas: la entrada de autoload files de Composer del paquete y el Registrar del paquete. Un error de función no definida significa que la entrada files no se cargó.

Ejecutar composer dump-autoload para reconstruir la lista de autoload files.
Confirmar que nextpdf/codeigniter aparece en vendor/composer/autoload_files.php.
Como alternativa, llamar directamente a Services::pdf(false) o Services::pdfDocument(false). Los helpers son envoltorios ligeros sobre estas llamadas.

Configuración

`.env`: las anulaciones se ignoran

Para resolver una anulación, BaseConfig usa como prefijo el nombre corto de la clase en minúsculas. La clase es NextPdf, por lo que el prefijo es nextpdf. No es nextPdf ni NextPdf.

Usar nextpdf.fontsPath, no nextPdf.fontsPath.
Indicar una clave anidada con un punto: nextpdf.signature.certificate.
La forma completamente cualificada NextPDF\CodeIgniter\Config\NextPdf.fontsPath también funciona.

Un arreglo de configuración completo vuelve a los valores predeterminados

Al extender la clase NextPdf y asignar un arreglo parcial, se reemplaza el arreglo completo. Por eso, proporcionar todas las claves del arreglo que se anule. Para ver un ejemplo de arreglo completo, consultar /integrations/codeigniter/configuration/.

Errores en tiempo de ejecución

`RuntimeException: NextPDF requires the ext-… PHP extension`

El registro de fuentes valida mbstring y zlib una vez por proceso. Este error se genera con el nombre de la extensión que falta. Instalar o habilitar la extensión indicada en el entorno de ejecución de PHP. Después, reiniciar el worker o el pool de PHP-FPM.

`RuntimeException: NextPdf fontsPath contains invalid characters`

El registro de fuentes rechaza un fontsPath que contenga un envoltorio de flujo (://) o un byte nulo. Establecer fontsPath en una ruta de sistema de archivos simple. No apuntarlo a una ruta con envoltorio, como php://, phar:// o similar.

Problemas de respuesta

El nombre de archivo se muestra incorrecto en la descarga

PdfResponse sanea los nombres de archivo. El comportamiento verificado es el siguiente:

Un nombre de archivo vacío o que solo contiene espacios se convierte en document.pdf.
A un nombre sin extensión .pdf (o .PDF) se le añade .pdf al final. Un .PDF existente se conserva tal cual.
Un nombre con caracteres no ASCII produce una alternativa ASCII y un parámetro RFC 5987 filename*=UTF-8''…, de modo que los navegadores modernos muestran el nombre original. Este comportamiento es esperado, no un error.
Los separadores de ruta, los bytes nulos y los CR/LF se eliminan.

La respuesta no incluye encabezados de seguridad

Cada respuesta PdfResponse incluye X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, X-Robots-Tag y Referrer-Policy. Si están ausentes en el cliente, un proxy o la aplicación los está eliminando o sobrescribiendo más adelante. Inspeccionar la respuesta antes y después del proxy inverso.

Cola

`QueueException` al encolar el job

La cola compara el nombre del job encolado con las claves de Config\Queue::$jobHandlers y rechaza cualquier nombre que no esté registrado. Registrar el job con una clave de nombre y luego encolar ese nombre:

public array $jobHandlers = ['generate-pdf' => GeneratePdfJob::class];

// dispatch
\service('queue')->push('pdf-queue', 'generate-pdf', [...]);

Encolar GeneratePdfJob::class como nombre del job produce un fallo. El segundo argumento es una clave de nombre, no una cadena de clase.

`InvalidArgumentException` desde el job

El job valida su payload antes de realizar cualquier trabajo. Los casos de rechazo verificados y sus mensajes son:

Causa	Fragmento del mensaje
`builder` ausente, vacío o que no sea una cadena	`non-empty static callable string`
`builder` fuera de `App\PdfBuilders`	`not allowed`
`builder` coincide con el patrón pero no es invocable	`not a valid callable`
`outputPath` ausente o vacío	`non-empty string`
`outputPath` fuera de `WRITEPATH/pdfs/`	`outside of allowed directory`
`outputPath` que no termine en `.pdf`	`must end with .pdf`

Corregir el payload para que el builder sea un invocable estático App\PdfBuilders\<Class>::<method>. Asegurarse de que la ruta de salida se resuelva dentro de WRITEPATH/pdfs/ con una extensión .pdf.

`class … BaseJob not found`

codeigniter4/queue es una dependencia solo de desarrollo del paquete. La aplicación que ejecuta los workers debe requerirla directamente:

composer require codeigniter4/queue

Diagnóstico

composer show nextpdf/codeigniter — confirmar que el paquete se resolvió.
composer dump-autoload — reconstruir el descubrimiento y el autoload de los helpers.
php spark routes — confirmar que las rutas de PDF están registradas.
La comprobación de descubrimiento más rápida consiste en usar un controlador que llame a Services::pdfDocument(false) y compruebe que el resultado es un Document.

Conformidad

Asignación de clase a ruta — relevante para los fallos de descubrimiento (PSR-4 Autoloader §x1.x3).

Consulta también

/integrations/codeigniter/install/ — requisitos de descubrimiento.
/integrations/codeigniter/configuration/ — el prefijo .env y la regla de anulación de arreglos.
/integrations/codeigniter/production-usage/ — registro correcto de la cola.
/integrations/codeigniter/boot-and-discovery/ — la secuencia de descubrimiento.