Resumen de la integración de NextPDF con Symfony

De un vistazo

nextpdf/symfony es el bundle oficial para usar el motor NextPDF con Symfony 7. Conecta el motor con el contenedor de Symfony y ofrece una factoría de documentos que se puede inyectar en servicios propios. También incluye ayudantes de respuesta HTTP y una vía de generación asíncrona de PDF, para que el trabajo pueda ejecutarse en segundo plano.

Qué proporciona el bundle

El bundle de NextPDF para Symfony enlaza el motor nextpdf/core con una aplicación Symfony como un bundle estándar. Añade los componentes básicos que se indican a continuación, todos verificados contra el código fuente del bundle en src/Symfony/:

• Un punto de entrada del bundle: NextPDF\Symfony\NextPdfBundle extiende la clase base Bundle de Symfony y registra un compiler pass.
• Una extensión de inyección de dependencias: NextPDF\Symfony\DependencyInjection\NextPdfExtension carga las definiciones de servicios, traduce el árbol de configuración a parámetros del contenedor y expone el alias de configuración nextpdf.
• Un árbol de configuración tipado: NextPDF\Symfony\DependencyInjection\Configuration define el esquema de configuración de nextpdf. El esquema valida valores de enumeración, establece valores predeterminados y usa marcadores de posición de parámetros %kernel.*%.
• Una factoría de documentos inyectable: NextPDF\Symfony\Service\PdfFactory produce nuevas instancias preconfiguradas de NextPDF\Core\Document. Es el equivalente en Symfony de una fachada estática.
• Ayudantes de respuesta HTTP: NextPDF\Symfony\Http\PdfResponse construye respuestas en línea, de descarga y por streaming con un conjunto fijo de cabeceras de seguridad alineadas con OWASP.
• Una vía de generación asíncrona: NextPDF\Symfony\Message\GeneratePdfMessage, NextPDF\Symfony\Message\GeneratePdfHandler y NextPDF\Symfony\Message\PdfBuilderInterface se integran con Symfony Messenger para que el renderizado de PDF pueda ejecutarse en un worker.
• Un detector de extensiones en tiempo de compilación: NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass detecta extensiones opcionales de NextPDF y registra sus servicios solo cuando esas extensiones están presentes.

Contrato del contenedor

El bundle registra un conjunto pequeño y estable de servicios públicos del contenedor. El servicio de documentos nextpdf.document (con alias NextPDF\Contracts\PdfDocumentInterface y NextPDF\Core\Document) no es compartido: cada resolución devuelve un documento distinto y desechable. Esto coincide con el contrato del contenedor PSR-11, según el cual dos llamadas sucesivas a get() con el mismo identificador pueden devolver valores diferentes según la configuración del contenedor; consulta PSR-11 §1.1.2. El enlace no compartido es deliberado: un documento acumula estado en cada renderizado, por lo que una instancia nueva por solicitud evita filtraciones de estado entre solicitudes en workers de larga duración.

El registro de fuentes (NextPDF\Contracts\FontRegistryInterface) funciona al revés: es un singleton compartido. El registro de imágenes está etiquetado con kernel.reset, de modo que su caché acotada se vacía entre solicitudes en FrankenPHP y en los workers de Messenger. La página de configuración documenta la tabla completa de servicios y alias.

Registro de eventos opcional

Los registros de fuentes e imágenes pueden recibir un logger PSR-3 opcional. El bundle enlaza Psr\Log\LoggerInterface solo si la aplicación proporciona uno (nullOnInvalid()). Por tanto, el registro de eventos es un colaborador opcional y no una dependencia obligatoria. Esto es coherente con el contrato del logger PSR-3, según el cual un logger es un colaborador inyectado e intercambiable (PSR-3).

Capacidades del núcleo frente a opcionales

El bundle en sí es software de núcleo con licencia Apache-2.0. Algunas capacidades están disponibles únicamente cuando se instala un paquete opcional junto con él:

Capacidad	Requiere	Detección
Generación de PDF, PdfFactory, PdfResponse	solo el núcleo	siempre disponible
Generación asíncrona	symfony/messenger	el handler se activa cuando Messenger está instalado
Renderizado de HTML con Chrome CDP	nextpdf/artisan	detección con class_exists en tiempo de compilación
Archivado PDF/A, firmas digitales	nextpdf/premium (instala Pro)	detección con class_exists en tiempo de compilación

Cuando nextpdf/premium está instalado, el bundle puede aplicar una configuración de firma PAdES base B-B. Los perfiles de firma más avanzados quedan fuera del alcance de la documentación de este bundle. Para ver la matriz de ediciones, consulta la documentación de NextPDF Premium.

Cuándo usar este bundle

Conviene usar nextpdf/symfony cuando se construyen PDF dentro de una aplicación HTTP o de un worker de Symfony 7. El bundle ofrece servicios gestionados por el contenedor, registros seguros para workers y respuestas de descarga seguras, por lo que no hace falta conectar el motor manualmente. Si solo se necesita una generación puntual en un script, basta con usar el paquete de núcleo nextpdf/core por sí solo.

Conformidad

Cada fila contiene 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) está en _sidecars/rag-citations.yaml.

Especificación	Cláusula	reference_id	Afirmación
PSR-11	psr_11_container#1.1.2.p3.b		Contrato del valor de retorno de get() del contenedor
PSR-3	psr_3_logger#x3.p17		Dependencia opcional de LoggerInterface

Contexto comercial

Las firmas digitales y el archivado PDF/A pasan a estar disponibles cuando nextpdf/premium (Pro) se instala junto con el bundle. Esta es una capacidad Pro opcional. El bundle de núcleo documentado aquí no requiere cambios de código para adoptarla. Consulta </get-license/?intent=symfony-pro>.

Consulta también

• /integrations/symfony/install/: instala y registra el bundle.
• /integrations/symfony/configuration/: el árbol de configuración completo de nextpdf y la tabla de servicios.
• /integrations/symfony/quickstart/: un controlador ejecutable y un ejemplo asíncrono.
• /integrations/symfony/boot-and-discovery/: cómo Symfony descubre y arranca el bundle.
• /integrations/symfony/production-usage/: seguridad de los workers, streaming y patrones asíncronos.