Referencia de la API de Symfony

De un vistazo

El paquete de Symfony expone el registro del bundle, un árbol de configuración, una fábrica inyectable para documentos nuevos, ayudantes de respuesta HTTP y tipos de Messenger para la generación asíncrona. Casi todo el código de la aplicación interactúa solo con dos símbolos: el servicio PdfFactory, que se inyecta para construir un Document, y el ayudante PdfResponse, que convierte ese documento en una respuesta HTTP segura. Los símbolos restantes (bundle, extensión, compiler pass, árbol de configuración, DTO de Messenger y handler) son piezas de cableado que se configuran una sola vez o que el framework gestiona automáticamente.

Punto de partida: para empezar, inyectar NextPDF\Symfony\Service\PdfFactory, llamar a create() para obtener un Document nuevo y devolverlo con NextPDF\Symfony\Http\PdfResponse::download(). El primer ejemplo siguiente muestra exactamente ese flujo.

Tareas comunes

Tres fragmentos ejecutables para las tareas más frecuentes. Cada uno usa solo los símbolos verificados documentados en las tablas siguientes.

Devolver una descarga de PDF desde un controlador: inyectar la fábrica, construir un documento y pasarlo al ayudante de respuesta:

<?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 InvoiceController
{
    #[Route('/invoice/{number}', name: 'invoice_pdf')]
    public function download(PdfFactory $pdf, string $number): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, "Invoice #{$number}");

        return PdfResponse::download($doc, "invoice-{$number}.pdf");
    }
}

Qué hace: PdfFactory::create() devuelve un Document nuevo y preconfigurado. PdfResponse::download() lo envía con Content-Type: application/pdf, disposición como adjunto y las cabeceras de seguridad fijas del bundle.

Transmitir un PDF grande para mantener bajo el pico de memoria: usar otro ayudante y devolver un StreamedResponse:

<?php

declare(strict_types=1);

namespace App\Controller;

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

final class ReportController
{
    #[Route('/report', name: 'report_pdf')]
    public function report(PdfFactory $pdf): StreamedResponse
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, 'Annual report');

        return PdfResponse::streamDownload($doc, 'annual-report.pdf');
    }
}

Qué hace: PdfResponse::streamDownload() emite el PDF materializado por fragmentos y omite Content-Length; para el equivalente en línea, usar streamInline().

Despachar un PDF para generación asíncrona: enviar un GeneratePdfMessage a un transporte de Messenger para que el renderizado se ejecute en un worker:

<?php

declare(strict_types=1);

namespace App\Controller;

use App\Pdf\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Routing\Attribute\Route;

final class QueueController
{
    #[Route('/invoice/{id}/queue', name: 'invoice_queue')]
    public function queue(MessageBusInterface $bus, int $id): Response
    {
        $bus->dispatch(new GeneratePdfMessage(
            builderClass: InvoicePdfBuilder::class,
            outputPath: '/var/storage/invoices/' . $id . '.pdf',
            builderContext: ['invoice_id' => $id],
        ));

        return new Response('PDF generation queued.', 202);
    }
}

Qué hace: el DTO lleva un class-string de builder y una ruta de salida validada. El handler resuelve el builder, construye el documento y lo guarda en el worker. La clase del builder implementa PdfBuilderInterface y se registra en un service locator (consultar el quickstart de Symfony para el locator y el cableado del worker).

Fábrica

Consultar esta tabla cuando se necesite el constructor exacto y el contrato de create() del servicio inyectable que produce documentos nuevos.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)	factory: fábrica del núcleo; defaults: creador, autor, idioma, márgenes; pdfa: perfil PDF/A opcional; artisanConfig: configuración opcional del renderer de Chrome.	Los valores predeterminados se aplican solo cuando están configurados.	PdfFactory	Errores de cableado del contenedor.	El servicio puede ser singleton porque create() devuelve un documento nuevo.
PdfFactory::create()	ninguno.	Aplica el creador y el idioma; aplica el autor solo cuando no está vacío; aplica PDF/A y la configuración de Artisan solo cuando están disponibles.	NextPDF\Core\Document	Errores de configuración del núcleo.	Usar una vez por solicitud, comando o mensaje.
PdfFactory::setArtisanAvailable(bool $available)	available: indicador de disponibilidad en tiempo de compilación.	Desactivado hasta que el compiler pass lo habilita.	void	ninguno esperado.	Hook interno invocado por el compiler pass opcional de la extensión.
PdfFactory::setProAvailable(bool $available)	available: indicador de disponibilidad en tiempo de compilación.	Desactivado hasta que el compiler pass lo habilita.	void	ninguno esperado.	Hook interno para la disponibilidad de Premium.

Bundle, extensión y configuración

Esta tabla cubre la capa de cableado: consultarla al registrar el bundle, resolver el árbol de configuración nextpdf o rastrear la detección de extensiones opcionales. La segunda tabla enumera las claves de configuración.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
NextPdfBundle::build(ContainerBuilder $container)	Constructor del contenedor de Symfony.	Llama al método build del padre y registra OptionalExtensionPass.	void	Errores de registro del compiler pass.	Habilita la detección de las funciones opcionales de Artisan y Premium.
NextPdfBundle::getPath()	ninguno.	Devuelve la ruta raíz del paquete.	string	ninguno esperado.	Lo usan el descubrimiento de bundles de Symfony y la carga de recursos.
NextPdfExtension::load(array $configs, ContainerBuilder $container)	Arrays de configuración del usuario y constructor de contenedor.	Procesa la configuración nextpdf, almacena los parámetros resueltos, carga las definiciones de servicios y luego comprueba las extensiones requeridas.	void	Errores de validación de configuración, de carga de servicios o de extensión faltante.	Las extensiones requeridas son mbstring y zlib.
NextPdfExtension::getAlias()	ninguno.	Usa nextpdf como clave de configuración raíz.	string	ninguno esperado.	Configura el bundle bajo nextpdf:.
Configuration::getConfigTreeBuilder()	ninguno.	Define el árbol de configuración validado nextpdf.	TreeBuilder	Errores de definición de configuración de Symfony.	Refleja la forma de la configuración de Laravel cuando resulta práctico.
OptionalExtensionPass::process(ContainerBuilder $container)	Constructor del contenedor de Symfony.	Detecta los servicios opcionales de Artisan y Premium y ajusta los indicadores de disponibilidad de la fábrica.	void	Errores de cableado del compiler pass.	Se ejecuta durante la compilación del contenedor.

Clave de configuración	Tipo	Comportamiento predeterminado	Notas
page_format	enum	A4; los valores permitidos incluyen A3, A5, Letter, Legal y Tabloid.	Se aplica a la creación predeterminada de documentos.
orientation	enum	P; los valores permitidos son P y L.	Usar llamadas explícitas del documento cuando una página necesite una orientación diferente.
unit	enum	mm; los valores permitidos son pt, mm, cm y in.	Mantiene los valores predeterminados del framework alineados con las unidades del núcleo.
pdfa	`string	null`	null; los valores permitidos son 4, 4e y 4f.
fonts_path / cache_path	string	Ruta de fuentes del proyecto y ruta de caché del kernel.	Mantener ambas rutas legibles o escribibles según el rol de ejecución.
signature.*	array	Desactivado de forma predeterminada con el nivel de firma B-B.	Proporciona certificado, clave, contraseña, certificados adicionales y nivel.
tsa.*	array	Desactivado cuando la URL es null; el tiempo de espera es de 30 segundos de forma predeterminada.	Admite credenciales, archivos mTLS, anclajes de clave pública y política HTTP.
ocsp_cache.*	array	Activado con un TTL de 86400 segundos.	Lo usan los flujos de validación y de firma a largo plazo cuando está disponible.
messenger.*	array	Transporte async, tiempo de espera 120, 3 reintentos.	Lo usan los flujos de trabajo de generación asíncrona.
artisan.*	array	El renderer de Chrome está desactivado a menos que esté configurado e instalado.	Se mapea a ChromeRendererConfig cuando el renderer opcional está disponible.
defaults.*	array	Creador NextPDF, autor vacío, idioma en, márgenes y fuente predeterminados.	Aplicado por PdfFactory::create().

Respuestas HTTP

Usar esta tabla para elegir el ayudante de respuesta adecuado (visualización en línea frente a descarga, respuesta en búfer frente a transmisión) y para ver el comportamiento del nombre de archivo y las cabeceras de cada uno.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: documento construido; filename: nombre de archivo de la respuesta.	Añade .pdf cuando falta.	Symfony\Component\HttpFoundation\Response	Errores de serialización del núcleo.	Establece el tipo de contenido PDF y cabeceras defensivas.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Igual que inline; la disposición es de adjunto.	Respuesta de descarga en el navegador.	Response	Igual que inline.	Usar para descargas explícitas.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Igual que inline.	Emite los bytes del PDF materializado por fragmentos.	StreamedResponse	Igual que inline.	No evita la materialización del documento.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Igual que streamInline; la disposición es de adjunto.	Respuesta de descarga por transmisión.	StreamedResponse	Igual que streamInline.	Aplica la política de tamaño de salida antes de renderizar.

Messenger

Consultar esta tabla al construir la ruta asíncrona: el DTO de mensaje que se despacha, la interfaz de builder que se implementa y el handler que se ejecuta en el worker.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])	builderClass: class-string que implementa PdfBuilderInterface; outputPath: .pdf de destino; builderContext: datos serializables.	Array de contexto vacío.	DTO de mensaje.	InvalidArgumentException por FQCN no válido, envoltorio de flujo, byte nulo, traversal, ruta vacía o destino que no es .pdf.	Los transportes de Messenger transportan datos, no closures.
PdfBuilderInterface::build(Document $document, array $context): Document	document: documento nuevo configurado; context: datos serializables del mensaje.	Sin contexto predeterminado más allá del valor del mensaje.	Un Document configurado.	Excepciones específicas del builder.	Mantener los builders deterministas e idempotentes.
new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)	Fábrica de PDF y service locator de builders etiquetados.	No se crea ningún documento durante la construcción.	GeneratePdfHandler	Errores de cableado del contenedor.	El locator debería exponer solo implementaciones de PdfBuilderInterface.
GeneratePdfHandler::__invoke(GeneratePdfMessage $message)	message: DTO de mensaje validado.	Resuelve el builder desde el contenedor, construye el documento y lo guarda.	void	Servicio de builder faltante, resultado de builder no válido, errores de escritura del núcleo.	Preferir los builders de servicio sobre las devoluciones de llamada estáticas.

Notas de desarrollo

• No almacenar un Document como servicio. Almacenar PdfFactory y llamar a create() para cada unidad de trabajo.
• Encolar solo contexto serializable. No poner flujos abiertos, closures ni objetos de solicitud en builderContext.
• Mantener la política de ruta de salida más estricta que el DTO cuando el despliegue tenga raíces de almacenamiento específicas por inquilino.