Arranque y descubrimiento de NextPDF en CodeIgniter

De un vistazo

CodeIgniter 4 descubre automáticamente la clase Services del paquete, sus funciones helper y el registrar mediante el descubrimiento de paquetes de Composer. Esta página explica la secuencia exacta y la configuración que la controla.

Cómo funciona el descubrimiento de Services en CodeIgniter

CodeIgniter 4 resuelve un servicio examinando cada clase Config\Services descubierta para encontrar un método estático cuyo nombre coincida con el servicio solicitado. Así, cuando la aplicación llama a service('pdf'), el framework encuentra la primera clase Services descubierta que declara un método pdf y lo invoca.

El descubrimiento se rige por Config\Modules:

• $enabled: conmutador principal del descubrimiento automático. Valor predeterminado true.
• $discoverInComposer: amplía el descubrimiento a los paquetes de Composer. Valor predeterminado true. Esta marca permite que el framework encuentre nextpdf/codeigniter.
• $composerPackages: un filtro opcional only / exclude para el conjunto de paquetes de Composer.
• $aliases: los tipos de elementos que participan en el descubrimiento. El valor predeterminado del framework incluye services y registrars, ambos usados por este paquete.

La clase del paquete es NextPDF\CodeIgniter\Config\Services. Composer asigna el prefijo PSR-4 NextPDF\CodeIgniter\ a src/CodeIgniter/. Un nombre de clase totalmente cualificado debe incluir un espacio de nombres de nivel superior (PSR-4 §x1.x2.p5, modal MUST). El prefijo del espacio de nombres se asigna al directorio base, por lo que la clase queda resuelta en su archivo (PSR-4 §x1.x3).

Secuencia de arranque

1. Autoload de Composer. Composer registra el mapa PSR-4 y las entradas de autoload files. El archivo helper src/CodeIgniter/Helpers/pdf_helper.php se carga en este paso.
2. Bootstrap del framework. CodeIgniter lee Config\Modules. Cuando el descubrimiento está habilitado, construye la lista de elementos descubiertos en los paquetes de Composer.
3. Descubrimiento de registrars. El framework recopila las clases Registrar. El Registrar::Autoload() del paquete registra el helper pdf en el cargador de helpers de CodeIgniter.
4. Resolución del servicio en la primera llamada. La resolución de las factorías de servicios es diferida. La primera llamada a service('pdf') o Services::pdf() ejecuta la factoría. Los servicios compartidos se guardan en caché en el localizador mientras dura el proceso.

Enlaces del contenedor

CodeIgniter 4 no incluye un contenedor PSR-11. Los «enlaces» son los métodos estáticos de factoría de la clase Services. Cada método acepta un parámetro bool $getShared:

Servicio	Compartido de forma predeterminada	Notas
fontRegistry	sí	Se precalienta y luego se bloquea.
imageRegistry	sí	Caché LRU acotada.
documentFactory	sí	Sin estado.
pdfDocument	no	Nueva instancia en cada llamada.
pdf	no	Nueva instancia en cada llamada.
tsaClient	sí	null si no hay URL de TSA.
pdfSigner	no	null si la firma está deshabilitada.

Las instancias compartidas residen en la caché de instancias de BaseService de CodeIgniter durante el proceso. El entorno de pruebas del framework limpia esa caché mediante BaseService::reset(), y las pruebas funcionales del paquete dependen de ese reinicio entre casos.

Orden de resolución de la configuración

La configuración efectiva se resuelve en este orden:

1. Los valores predeterminados del paquete en NextPDF\CodeIgniter\Config\NextPdf.
2. Una clase de la aplicación Config\NextPdf que extiende la clase del paquete, si existe. CodeIgniter la carga en lugar del valor predeterminado del paquete.
3. Sobrescrituras de entorno aplicadas por BaseConfig, indexadas por el nombre corto de clase en minúsculas nextpdf (claves anidadas con puntos, o la forma de clase totalmente cualificada).

El archivo de extensión de configuración de la aplicación declara una sola clase y no ejecuta efectos secundarios. Así se mantiene alineado con la expectativa de PSR-1 de que un archivo o bien declare símbolos o bien ejecute lógica con efectos secundarios, pero no ambas cosas (PSR-1 §x1.x1.p3). El archivo helper es la contraparte diseñada deliberadamente para tener efectos secundarios. Declara las funciones globales pdf() y pdf_document(), y cada una está protegida por una comprobación con function_exists para que una carga doble sea segura.

Diagnóstico

• composer dump-autoload: reconstruye el mapa PSR-4 y la lista de autoload files después de una actualización.
• La comprobación de descubrimiento más rápida es un controlador que llama a Services::pdfDocument(false) y comprueba que devuelve un Document.
• Inspeccionar vendor/composer/autoload_files.php para confirmar que el archivo helper está registrado.
• Consultar /integrations/codeigniter/troubleshooting/ para ver la correspondencia entre fallos y causas.

Conformidad

• Un nombre de clase totalmente cualificado requiere un espacio de nombres de nivel superior (PSR-4 Autoloader §x1.x2.p5).
• Asignación del prefijo del espacio de nombres a la ruta de clase del directorio base (PSR-4 Autoloader §x1.x3).
• Un archivo declara símbolos o causa efectos secundarios: el diseño del archivo helper (PSR-1 Basic Coding Standard §x1.x1.p3).

Véase también

• /integrations/codeigniter/integration/: la referencia de integración y la prueba de humo.
• /integrations/codeigniter/install/: instalación y verificación del descubrimiento.
• /integrations/codeigniter/overview/: la superficie completa de la API.
• /integrations/codeigniter/troubleshooting/: modos de fallo del descubrimiento.