Guía para desarrolladores de CodeIgniter

De un vistazo

El paquete de CodeIgniter expone factorías de servicios, funciones auxiliares y un pequeño envoltorio de biblioteca Pdf para un documento. Este envoltorio resulta práctico en controladores. El trabajo en cola usa constructores invocables (callables) estáticos porque las cargas útiles de la cola de CodeIgniter son datos serializados.

Usar esta guía al diseñar flujos de controlador, servicios, constructores de cola o pruebas en torno a nextpdf/codeigniter.

Límite de la arquitectura

Capa	Propiedad de	Responsabilidad	No poner aquí
Controlador	Aplicación	Autorizar, llamar a un constructor o servicio, y devolver un `DownloadResponse`.	Lógica de diseño compartida.
Envoltorio de biblioteca	`nextpdf/codeigniter`	Envolver un `Document` y proporcionar funciones auxiliares response/save.	Almacenamiento de documentos de larga duración.
Factoría de servicios	`nextpdf/codeigniter`	Crear registros compartidos y documentos nuevos.	Raíces de almacenamiento específicas del negocio.
Constructor de cola	Aplicación	Construir un documento a partir de una entrada invocable estática.	Objetos de solicitud o estado no serializable.
Motor central	`nextpdf/nextpdf`	Construir y serializar el PDF.	Política de respuesta o de cola de CodeIgniter.

Ciclo de vida en tiempo de ejecución

Etapa	Comportamiento	Acción del desarrollador
Registro de carga automática	`Registrar::Autoload()` registra la carga de funciones auxiliares para el módulo.	Cargar el módulo a través de la configuración de CodeIgniter.
Resolución de servicios	`Services::pdf()` devuelve, de forma predeterminada, un envoltorio alrededor de un documento nuevo.	Resolver una vez por solicitud.
Creación de contenido	El código de la aplicación usa `Pdf::document()` para las llamadas al documento central.	Mantener el código de construcción de documentos en servicios o constructores.
Respuesta	`PdfResponse` devuelve un `DownloadResponse`.	Dejar que el paquete establezca los encabezados del PDF.
Ejecución en cola	`GeneratePdfJob::process()` valida el constructor y la ruta de salida, y luego guarda.	Colocar los constructores de cola bajo `App\PdfBuilders`.

Estructura recomendada de la aplicación

Ruta	Propósito
`app/PdfBuilders/*`	Constructores estáticos seguros para la cola aceptados por `GeneratePdfJob`.
`app/Libraries/*`	Envoltorios opcionales de la aplicación en torno a flujos de trabajo de documentos repetidos.
`app/Services/*`	Recuperación de datos de dominio y política de almacenamiento.
`app/Config/NextPdf.php`	Sustituciones de la aplicación para la configuración del paquete.
`tests/app/PdfBuilders/*`	Pruebas de constructores y de cargas útiles de la cola.

Usar las funciones auxiliares del paquete para flujos cortos. Usar llamadas explícitas a servicios cuando la construcción del documento pertenezca a una clase que deba probarse directamente.

<?php

namespace App\Controllers;

final class InvoiceController extends BaseController
{
    public function download(int $id)
    {
        $pdf = pdf();
        $pdf->document()
            ->setTitle('Invoice ' . $id)
            ->addPage()
            ->writeHtml('<h1>Invoice ' . $id . '</h1>');

        return $pdf->download('invoice-' . $id . '.pdf');
    }
}

Patrón de constructor de cola

Los constructores de cola deben ser estáticos, deterministas y estar ubicados bajo App\PdfBuilders. Mantener el arreglo de contexto lo bastante simple como para serializarlo y auditarlo.

<?php

namespace App\PdfBuilders;

use NextPDF\Core\Document;

final class InvoiceBuilder
{
    public static function build(Document $document, array $context): Document
    {
        $document->setTitle((string) $context['title'])
            ->addPage()
            ->writeHtml((string) $context['html']);

        return $document;
    }
}

El trabajo restringe la salida al directorio de PDF configurado para la aplicación. Si la aplicación necesita almacenamiento específico por inquilino, colocar esa política en un único servicio y probarla antes del despacho a la cola.

Puntos de extensión

Punto de extensión	Uso	Restricción
`Services::pdfDocument()`	Personalización de la creación de documentos.	Debe devolver un documento nuevo.
`Services::fontRegistry()`	Precalentamiento de fuentes y acceso al registro.	Rechazar las rutas no seguras y mantener el registro bloqueado tras el precalentamiento.
`Services::pdfSigner()`	Firma digital opcional.	Devolver `null` cuando la firma esté desactivada.
`NextPDF\CodeIgniter\Libraries\Pdf`	Envoltorio orientado al controlador.	Un envoltorio se corresponde con un documento.
`App\PdfBuilders::*`	Constructores de documentos seguros para la cola.	Se requiere una cadena invocable estática.
`app/Config/NextPdf.php`	Valores predeterminados de la aplicación y ajustes de integración.	Mantener explícitos los valores de producción.

Flujo de trabajo de desarrollo

Empezar con un controlador que llame a pdf() o service('pdf').
Trasladar la construcción repetida de documentos a app/PdfBuilders o a un servicio de la aplicación.
Usar GeneratePdfJob cuando la generación sea demasiado lenta para la ruta de la solicitud.
Mantener el contexto de la cola serializable y pequeño.
Almacenar la salida bajo la raíz de almacenamiento de PDF aprobada, salvo que la política se extienda deliberadamente.
Añadir pruebas para las funciones auxiliares, los servicios, las cargas útiles de la cola y las rutas no seguras.

Manejo de fallos

Fallo	Dónde debe manejarse	Respuesta recomendada
Extensión faltante o ruta de fuente no segura	Factoría de servicios.	Fallar rápido durante la resolución del servicio.
Invocable de constructor no válido	Validación del trabajo en cola.	Rechazar el trabajo y registrar la cadena del constructor sin secretos.
Ruta de salida no segura	Servicio de almacenamiento y trabajo en cola.	Rechazar antes del despacho y mantener la validación del trabajo.
Error de serialización de la respuesta	Manejo de errores del controlador o del framework.	No enviar un cuerpo de respuesta parcial.
Clase Premium opcional no disponible	Valor de retorno del método del servicio.	Manejar `null` de forma explícita antes de usar las funciones opcionales de factura electrónica.

Valores predeterminados seguros

Aspecto	Predeterminado	Cuándo sustituirlo
Espacio de nombres del constructor de cola	`App\PdfBuilders`.	Mantener el valor predeterminado salvo que también se actualice la política de seguridad.
Raíz de salida	`WRITEPATH/pdfs`.	Sustituirla solo con una lista de permitidos más estricta.
Nombre de archivo de la respuesta	`document.pdf`.	Usar nombres de archivo de negocio saneados.
Métodos de transmisión	Paridad de API con otros frameworks.	No apoyarse en la transmisión como límite de memoria en CodeIgniter.
Servicio de documentos	Nuevo de forma predeterminada.	No solicitar documentos compartidos en el código de la solicitud.

Lista de verificación de pruebas

Las pruebas de servicio verifican que cada resolución de Services::pdf() devuelva un documento independiente.
Las pruebas de las funciones auxiliares verifican que pdf() y pdf_document() devuelvan objetos nuevos.
Las pruebas de respuesta verifican los encabezados y la normalización del nombre de archivo.
Las pruebas de cola cubren cadenas de constructor no válidas y rutas de salida no seguras.
Las pruebas de constructor se ejecutan con datos de contexto representativos.
Las pruebas de configuración cubren la ruta de fuentes, la ruta de caché, la firma desactivada y los estados con TSA desactivado.