Integración de NextPDF con Symfony

En resumen

El flujo consiste en instalar nextpdf/symfony, dejar que Flex registre el bundle (o registrarlo manualmente), agregar config/packages/nextpdf.yaml e inyectar PdfFactory. Esta página sirve como índice de la integración; cada paso enlaza con una página más detallada.

Instalación

composer require nextpdf/symfony

El bundle requiere nextpdf/core^3.0 || ^5.2, symfony/*^7.2 y psr/log^3.0. Las clases se cargan automáticamente con el prefijo PSR-4 NextPDF\Symfony\, asignado a src/Symfony/. Un autoloader PSR-4 resuelve el prefijo del espacio de nombres en ese directorio base (PSR-4 §2). Para conocer los requisitos completos y los paquetes opcionales, consulta /integrations/symfony/install/.

Inicio y autodescubrimiento

Con Symfony Flex, la entrada extra.symfony.bundles del composer.json del bundle registra NextPDF\Symfony\NextPdfBundle para todos los entornos. Sin Flex, debe agregarse manualmente a config/bundles.php:

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

Para conocer la secuencia de inicio completa y el comportamiento del compiler pass, consulta /integrations/symfony/boot-and-discovery/.

Vínculos del contenedor

El archivo config/services.php del bundle registra estos servicios:

Servicio / alias	Ciclo de vida
`NextPDF\Symfony\Service\PdfFactory`	compartido, público — inyectar este
`nextpdf.document` → `PdfDocumentInterface` → `Document`	no compartido, público — nuevo en cada resolución
`NextPDF\Contracts\FontRegistryInterface`	compartido, bloqueado tras el precalentamiento
`NextPDF\Graphics\ImageRegistry`	compartido, `kernel.reset`
`NextPDF\Contracts\DocumentFactoryInterface`	compartido
`NextPDF\Symfony\Http\PdfResponse`	helper público sin estado

El vínculo del documento no es compartido a propósito. PSR-11 permite que un contenedor devuelva un valor distinto en llamadas sucesivas a get() para un mismo id. Un documento nuevo evita el estado compartido entre solicitudes en workers de larga duración (PSR-11 §1.1.2). Para consultar la tabla completa de servicios y alias, incluidos los vínculos condicionales de EInvoice, consulta /integrations/symfony/configuration/.

Publicar la configuración

El alias de configuración es nextpdf. Crear config/packages/nextpdf.yaml. Cuando se publica una recipe de Flex, esta deja una copia predeterminada. Cada clave tiene un valor predeterminado, por lo que un archivo mínimo se ve así:

nextpdf: ~

El árbol de configuración completo está documentado en /integrations/symfony/configuration/.

Primer uso

Inyectar PdfFactory y devolver después el resultado mediante PdfResponse:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class PdfController
{
    #[Route('/hello.pdf', name: 'hello_pdf')]
    public function hello(PdfFactory $pdf): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->cell(0, 10, 'Hello from NextPDF on Symfony.');

        return PdfResponse::inline($doc, 'hello.pdf');
    }
}

El controlador completo y la ruta asíncrona de Messenger están en /integrations/symfony/quickstart/.

Prueba de humo del bundle

La conexión puede confirmarse sin escribir código de aplicación:

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console lint:container

debug:container nextpdf debería listar PdfFactory, el alias nextpdf.document y los registries. lint:container verifica que cada argumento de servicio se resuelva. Para probar la generación, agregar el controlador anterior y solicitar después /hello.pdf.

Puntos de entrada de la API pública

Estos son los símbolos públicos admitidos para el código de aplicación:

Símbolo	Propósito
`NextPDF\Symfony\Service\PdfFactory::create()`	`Document` nuevo y preconfigurado
`NextPDF\Symfony\Http\PdfResponse::inline()` / `download()`	respuesta con búfer y encabezados de seguridad
`NextPDF\Symfony\Http\PdfResponse::streamInline()` / `streamDownload()`	respuesta transmitida por fragmentos
`NextPDF\Symfony\Message\GeneratePdfMessage`	DTO de generación asíncrona (validado)
`NextPDF\Symfony\Message\PdfBuilderInterface`	contrato de builder resuelto por el handler

Conformidad

Cada fila corresponde a una afirmación normativa de esta página. Cada afirmación está anclada a un reference_id completo de 64 caracteres hexadecimales del corpus SDO controlado. 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.p4`		Contrato de identificador has()/get() del contenedor
PSR-4	`psr_4_autoload#x1.x2.p5`		Asignación del espacio de nombres del autoloader

Consultar también

/integrations/symfony/install/ — requisitos y registro.
/integrations/symfony/boot-and-discovery/ — descubrimiento, inicio y compiler pass.
/integrations/symfony/configuration/ — esquema completo y tabla de servicios.
/integrations/symfony/quickstart/ — controlador ejecutable y ejemplo asíncrono.
/integrations/symfony/production-usage/ — seguridad de workers y transmisión.