Arranque y descubrimiento de NextPDF en Symfony

Vistazo general

El kernel registra NextPdfBundle. La extensión de DI del bundle carga services.php y resuelve el árbol de configuración como parámetros del contenedor. Después, un único compiler pass conecta las extensiones opcionales y el precalentamiento de fuentes.

Cómo Symfony Flex detecta el bundle

El composer.json del bundle declara una pista de autorregistro:

{
    "extra": {
        "symfony": {
            "bundles": {
                "NextPDF\\Symfony\\NextPdfBundle": "all"
            }
        }
    }
}

En una aplicación con Symfony Flex, esto añade NextPDF\Symfony\NextPdfBundle a config/bundles.php para todos los entornos (all). Sin Flex, el bundle debe añadirse manualmente en config/bundles.php. Symfony documenta oficialmente el modelo de registro de bundles (https://symfony.com/doc/current/bundles.html). Las clases del bundle se autocargan bajo el prefijo PSR-4 NextPDF\Symfony\, mapeado a src/Symfony/. Un autoloader PSR-4 asocia el prefijo del espacio de nombres con ese directorio base (PSR-4 §2).

Secuencia de arranque

La secuencia de arranque, verificada con el código fuente del bundle:

1. El kernel registra los bundles. Kernel::registerBundles() lee config/bundles.php e instancia NextPDF\Symfony\NextPdfBundle, que extiende Symfony\Component\HttpKernel\Bundle\Bundle.
2. Construcción del bundle. NextPdfBundle::build() llama al método de la clase padre y luego registra un único compiler pass: OptionalExtensionPass. NextPdfBundle::getPath() devuelve la raíz del paquete.
3. Carga de la extensión. La extensión de DI NextPDF\Symfony\DependencyInjection\NextPdfExtension (alias nextpdf) ejecuta processConfiguration() sobre Configuration. Establece los valores resueltos como parámetros del contenedor nextpdf.* y después carga config/services.php mediante un PhpFileLoader.
4. Comprobación de extensiones requeridas. NextPdfExtension::load() termina comprobando que ext-mbstring y ext-zlib estén presentes, y falla de inmediato si no lo están.
5. Ejecución del compiler pass. Durante la compilación del contenedor, OptionalExtensionPass::process() configura los indicadores de disponibilidad de extensiones en PdfFactory, registra condicionalmente el firmante y el cliente TSA, y programa el precalentamiento y el bloqueo del registro de fuentes.
6. Contenedor compilado y almacenado en caché. Symfony escribe el contenedor compilado. cache:warmup realiza este paso antes de que la aplicación reciba tráfico.

Compiler passes

El bundle registra exactamente un pass, NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass, añadido en NextPdfBundle::build(). Se ejecuta en el grupo de passes predeterminado (antes de la optimización). El pass realiza cuatro pasos. Cada paso incluye protecciones, por lo que no hace nada cuando sus entradas están ausentes:

• Indicadores de extensión — añade las llamadas a los métodos setArtisanAvailable(...) y setProAvailable(...) a la definición de PdfFactory. Los valores provienen de comprobaciones class_exists en tiempo de compilación para la factoría del navegador de Artisan y la clase PDF/A de Pro.
• Registro del firmante — cuando nextpdf.signature está presente, enabled es verdadero y hay un certificado configurado, registra una factoría de información de certificado y un servicio de firmante para el perfil base B-B.
• Cliente TSA — cuando nextpdf.tsa tiene una URL, registra un servicio de cliente TSA.
• Precalentamiento de fuentes — cuando nextpdf.preload_fonts no está vacío, añade las llamadas a los métodos warmup() y lock() a la definición del registro de fuentes.

Enlaces del contenedor

config/services.php define los servicios. El servicio de documento nextpdf.document (con alias NextPDF\Contracts\PdfDocumentInterface y NextPDF\Core\Document) está definido como no compartido: cada resolución devuelve un documento nuevo, lo que PSR-11 permite explícitamente — las llamadas sucesivas a get() para un mismo id pueden devolver valores distintos (PSR-11 §1.1.2). El registro de fuentes es compartido y se bloquea tras el precalentamiento. El registro de imágenes es compartido y está etiquetado como kernel.reset. La tabla completa está en /integrations/symfony/configuration/.

Orden de resolución de la configuración

1. Valores predeterminados integrados en Configuration (getConfigTreeBuilder()).
2. Anulaciones de la aplicación en config/packages/nextpdf.yaml, además de las anulaciones por entorno bajo config/packages/<env>/.
3. Symfony resuelve los marcadores de posición de parámetros %kernel.*%. Por ejemplo, fonts_path tiene como valor predeterminado %kernel.project_dir%/resources/fonts.
4. NextPdfExtension::load() escribe el resultado combinado en parámetros del contenedor nextpdf.* que consumen services.php y el compiler pass.

Los valores no válidos provocan un fallo en los pasos 1-2 con una InvalidConfigurationException de Symfony.

Diagnóstico

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console cache:clear

El primero enumera los servicios registrados. El segundo imprime la configuración combinada. El tercero reconstruye el contenedor y vuelve a ejecutar las comprobaciones de extensiones en tiempo de compilación.

Conformidad

Cada fila es una afirmación normativa formulada en esta página, anclada a un reference_id completo de 64 dígitos hexadecimales del corpus SDO restringido. La procedencia (manifiesto del corpus, transporte de recuperación) se encuentra en _sidecars/rag-citations.yaml.

Especificación	Cláusula	reference_id	Afirmación
PSR-11	psr_11_container#1.1.2.p3.b		La resolución del contenedor puede diferir en cada llamada
PSR-4	psr_4_autoload#x1.x2.p5		Mapeo de prefijo de espacio de nombres a directorio base

Véase también

• /integrations/symfony/integration/ — referencia de conexión de extremo a extremo.
• /integrations/symfony/install/ — instalación y registro.
• /integrations/symfony/configuration/ — árbol de configuración completo y tabla de servicios.
• /integrations/symfony/overview/ — resumen de capacidades.