Solución de problemas del bundle de NextPDF para Symfony

De un vistazo

La mayoría de los problemas se agrupan en cuatro áreas: descubrimiento, validación de la configuración, cableado del contenedor y enrutamiento de Messenger. Cada sección a continuación relaciona un síntoma con el comportamiento que lo verifica en el código fuente del bundle y proporciona un comando de consola para confirmar la solución.

El bundle no está registrado

Síntoma: PdfFactory no puede autocablearse, o debug:container nextpdf no devuelve resultados.

Causa: el bundle no se agregó a config/bundles.php. O bien Flex no se ejecutó, o bien la aplicación no usa Flex.

Solución:

php bin/console debug:container nextpdf

Si no devuelve resultados, agregar el bundle manualmente:

return [
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

La pista de registro automático se encuentra en el composer.json del bundle, bajo extra.symfony.bundles. Solo se aplica a aplicaciones con Flex habilitado.

El arranque falla por una extensión de PHP ausente

Síntoma: el kernel lanza una RuntimeException que menciona ext-mbstring o ext-zlib en el arranque.

Causa: esta es la protección deliberada de fallo rápido del bundle, NextPdfExtension::guardRequiredExtensions(). No es un defecto.

Solución: habilitar la extensión indicada en php.ini y reiniciar el runtime. Confirmarlo con:

php -m | grep -E 'mbstring|zlib'

La configuración se rechaza en tiempo de compilación

Síntoma: una Symfony\Component\Config\Definition\Exception\InvalidConfigurationException durante cache:clear o cache:warmup.

Causa: un valor queda fuera del esquema. Estas restricciones provienen de Configuration.php:

• page_format debe ser uno de A4, A3, A5, Letter, Legal, Tabloid.
• orientation debe ser P o L.
• unit debe ser uno de pt, mm, cm, in.
• pdfa debe ser null, 4, 4e o 4f.
• image_cache_mb debe ser >= 0.

Solución: imprimir la configuración fusionada y luego corregir la clave infractora:

php bin/console debug:config nextpdf

PDF/A o la firma no surten efecto

Síntoma: pdfa o la sección signature está configurada, pero la salida es un PDF común.

Causa: esas capacidades requieren nextpdf/premium. PdfFactory aplica PDF/A solo cuando la extensión Pro se detecta durante la compilación. El compiler pass registra un firmante solo cuando signature.enabled es verdadero y signature.certificate está configurado.

Solución: confirmar que Premium está instalado y que el servicio firmante existe:

composer show nextpdf/premium
php bin/console debug:container --show-private | grep -i signer

Si Premium está ausente, el bundle almacena la configuración, pero la deja inerte por diseño. La capacidad de firma documentada del bundle con Pro es el perfil base B-B. La documentación de NextPDF Premium cubre perfiles más allá de B-B.

El renderizado con Chrome no hace nada

Síntoma: la configuración de artisan se ignora.

Causa: el renderizado con Chrome mediante CDP requiere nextpdf/artisan. El compiler pass lo sondea con class_exists durante la compilación. Si la extensión está ausente, el renderer nunca queda cableado.

Solución:

composer show nextpdf/artisan
php bin/console cache:clear   # re-run the compile-time probe

El sondeo se ejecuta durante la compilación del contenedor. Por eso, después de instalar la extensión, ejecutar un nuevo cache:clear.

El manejador de Messenger nunca se invoca

Síntoma: GeneratePdfMessage se despacha, pero no se escribe ningún PDF.

Causas y soluciones:

• Mensaje no enrutado: agregar una entrada de enrutamiento que asigne NextPDF\Symfony\Message\GeneratePdfMessage a un transporte en config/packages/messenger.yaml y luego ejecutar un worker (php bin/console messenger:consume <transport>).
• Constructor ausente del localizador: el manejador obtiene el constructor desde un localizador PSR-11 usando como id la cadena del nombre de clase. Un identificador de contenedor es una cadena que identifica de forma única una entrada (PSR-11 §1.1.2). Si el localizador no tiene registrada la clase del constructor, el manejador lanza una RuntimeException que indica que el constructor configurado debe implementar PdfBuilderInterface. Registrar el constructor y luego referenciarlo desde el localizador.

Inspeccionar el enrutamiento y el localizador:

php bin/console debug:messenger
php bin/console debug:container --tag=container.service_locator

El mensaje se rechaza en el despacho con InvalidArgumentException

Síntoma: al construir GeneratePdfMessage, se lanza una InvalidArgumentException.

Causa: el objeto de transferencia de datos (DTO) del mensaje valida sus entradas. Las reglas de rechazo verificadas son las siguientes:

• una ruta de salida vacía o que contenga un byte nulo;
• un esquema de envoltorio de flujo (por ejemplo, php://...);
• un segmento de salto de directorio .. (separadores POSIX o de Windows);
• una ruta de salida que no termine en .pdf (sin distinguir mayúsculas de minúsculas);
• un builderClass que no es un nombre de clase sintácticamente válido.

Solución: pasar una ruta de sistema de archivos absoluta que termine en .pdf y un nombre de clase de constructor real y totalmente cualificado.

Un documento contiene datos obsoletos

Síntoma: un PDF generado incluye contenido de una solicitud anterior.

Causa: una instancia de Document se mantuvo entre solicitudes en un worker de larga ejecución. El servicio de documento es no compartido precisamente para evitarlo.

Solución: llamar a PdfFactory::create() dentro del método con ámbito de solicitud. Nunca almacenar el documento devuelto en un servicio compartido.

Referencia de comandos de diagnóstico

php bin/console debug:container nextpdf          # bundle services
php bin/console debug:config nextpdf             # merged configuration
php bin/console debug:container --show-private   # internal definitions
php bin/console debug:messenger                  # message routing
php bin/console messenger:consume <t> -vv        # verbose consume

Conformidad

Cada fila contiene una afirmación normativa de esta página, anclada a un reference_id completo de 64 hex del corpus SDO controlado. La procedencia, que abarca el manifiesto del corpus y el 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.p4		Contrato de identificador del contenedor para has()/get()

Véase también

• /integrations/symfony/install/: instalación y registro.
• /integrations/symfony/configuration/: esquema completo y restricciones.
• /integrations/symfony/boot-and-discovery/: secuencia de descubrimiento y arranque.
• /integrations/symfony/security-and-operations/: cabeceras de seguridad y validación de rutas.