Referência da API Symfony

Visão geral

O pacote Symfony expõe o registro do bundle, uma árvore de configuração, uma fábrica injetável para novos documentos, helpers de resposta do Hypertext Transfer Protocol (HTTP) e tipos do Messenger para geração assíncrona. A maior parte do código de aplicação usa apenas dois símbolos: o serviço PdfFactory, que você injeta para construir um Document, e o helper PdfResponse, que transforma esse documento em uma resposta HTTP segura. Os símbolos restantes (bundle, extensão, compiler pass, árvore de configuração, data transfer object (DTO) do Messenger e handler) compõem a ligação que você configura uma vez ou que o framework gerencia para você.

Comece por aqui: injete NextPDF\Symfony\Service\PdfFactory, chame create() para obter um Document novo e retorne-o com NextPDF\Symfony\Http\PdfResponse::download(). O primeiro exemplo mostra esse fluxo.

Tarefas comuns

Use estes três trechos executáveis nas tarefas mais comuns. Cada trecho usa apenas os símbolos verificados e documentados nas tabelas a seguir.

Retorne um download em Portable Document Format (PDF) a partir de um controller: injete a fábrica, construa o documento e passe-o para o helper de resposta:

<?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");
    }
}

O que ele faz: PdfFactory::create() retorna um Document novo e pré-configurado. PdfResponse::download() o envia com Content-Type: application/pdf, disposição de anexo e os cabeçalhos de segurança fixos do bundle.

Faça streaming de um PDF grande para manter baixo o pico de memória: use o helper de streaming e retorne um 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');
    }
}

O que ele faz: PdfResponse::streamDownload() emite o PDF materializado em blocos e omite Content-Length; use streamInline() para o equivalente inline.

Despache um PDF para geração assíncrona: envie um GeneratePdfMessage para um transporte do Messenger, de modo que a renderização rode em um 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);
    }
}

O que ele faz: o DTO carrega uma class-string de builder e um caminho de saída validado. O handler resolve o builder, constrói o documento e o salva no worker. A classe de builder implementa PdfBuilderInterface e é registrada em um service locator (consulte o quickstart do Symfony para a configuração do locator e do worker).

Fábrica

Use esta tabela para consultar o construtor exato e o contrato de create() do serviço injetável que produz documentos novos.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)	factory: fábrica do core; defaults: criador, autor, idioma, margens; pdfa: perfil PDF/A opcional; artisanConfig: configuração opcional do renderizador Chrome.	Os padrões são aplicados apenas quando configurados.	PdfFactory	Erros de ligação do container.	O serviço pode ser singleton porque create() retorna um documento novo.
PdfFactory::create()	nenhum.	Aplica criador e idioma; aplica autor apenas quando não vazio; aplica PDF/A e configuração do Artisan apenas quando disponíveis.	NextPDF\Core\Document	Erros de configuração do core.	Use uma vez por requisição, comando ou mensagem.
PdfFactory::setArtisanAvailable(bool $available)	available: flag de disponibilidade em tempo de compilação.	Desabilitado até que o compiler pass o habilite.	void	nenhum esperado.	Hook interno chamado pelo compiler pass da extensão opcional.
PdfFactory::setProAvailable(bool $available)	available: flag de disponibilidade em tempo de compilação.	Desabilitado até que o compiler pass o habilite.	void	nenhum esperado.	Hook interno para a disponibilidade do Premium.

Bundle, extensão e configuração

Use a primeira tabela para a camada de integração: registro do bundle, árvore de configuração nextpdf e detecção de extensões opcionais. A segunda tabela lista as chaves de configuração.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
NextPdfBundle::build(ContainerBuilder $container)	Container builder do Symfony.	Chama o método build pai e registra OptionalExtensionPass.	void	Erros de registro de compiler pass.	Habilita a detecção opcional de recursos do Artisan e do Premium.
NextPdfBundle::getPath()	nenhum.	Retorna o caminho raiz do pacote.	string	nenhum esperado.	Usado pela descoberta de bundles do Symfony e pelo carregamento de recursos.
NextPdfExtension::load(array $configs, ContainerBuilder $container)	Arrays de configuração do usuário e container builder.	Processa a configuração nextpdf, armazena os parâmetros resolvidos, carrega as definições de serviço e verifica as extensões obrigatórias.	void	Erros de validação de configuração, carregamento de serviço ou extensão ausente.	As extensões obrigatórias são mbstring e zlib.
NextPdfExtension::getAlias()	nenhum.	Usa nextpdf como a chave raiz de configuração.	string	nenhum esperado.	Configure o bundle sob nextpdf:.
Configuration::getConfigTreeBuilder()	nenhum.	Define a árvore de configuração validada nextpdf.	TreeBuilder	Erros de definição de configuração do Symfony.	Espelha o formato de configuração do Laravel onde for prático.
OptionalExtensionPass::process(ContainerBuilder $container)	Container builder do Symfony.	Detecta serviços opcionais do Artisan e do Premium e alterna as flags de disponibilidade da fábrica.	void	Erros de ligação de compiler pass.	Executa durante a compilação do container.

Chave de configuração	Tipo	Comportamento padrão	Observações
page_format	enum	A4; os valores permitidos incluem A3, A5, Letter, Legal e Tabloid.	Aplica-se à criação padrão de documentos.
orientation	enum	P; os valores permitidos são P e L.	Use chamadas explícitas no documento quando uma página precisar de uma orientação diferente.
unit	enum	mm; os valores permitidos são pt, mm, cm e in.	Mantém os padrões do framework alinhados com as unidades do core.
pdfa	`string	null`	null; os valores permitidos são 4, 4e e 4f.
fonts_path / cache_path	string	Caminho de fontes do projeto e caminho de cache do kernel.	Mantenha cada caminho legível ou gravável conforme seu papel em runtime.
signature.*	array	Desabilitado por padrão com nível de assinatura B-B.	Fornece certificado, chave, senha, certificados extras e nível.
tsa.*	array	Desabilitado quando o Uniform Resource Locator (URL) é null; o timeout tem padrão de 30 segundos.	Suporta credenciais, arquivos de mutual Transport Layer Security (mTLS), pins de chave pública e política de HTTP.
ocsp_cache.*	array	Habilitado com um time to live (TTL) de 86400 segundos.	Usado por fluxos de validação e de assinatura de longo prazo quando disponível.
messenger.*	array	Transporte async, timeout 120, 3 tentativas.	Usado por fluxos de geração assíncrona.
artisan.*	array	O renderizador Chrome fica desabilitado a menos que seja configurado e instalado.	Mapeia para ChromeRendererConfig quando o renderizador opcional está disponível.
defaults.*	array	Criador NextPDF, autor vazio, idioma en, margens e fonte padrão.	Aplicado por PdfFactory::create().

Respostas HTTP

Use esta tabela para escolher um helper de resposta por modo de exibição e buffering: exibição inline ou download, com buffer ou em streaming. Ela também mostra o comportamento de nome de arquivo e cabeçalhos.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: documento construído; filename: nome de arquivo da resposta.	Adiciona .pdf quando ausente.	Symfony\Component\HttpFoundation\Response	Erros de serialização do core.	Define o content type PDF e cabeçalhos defensivos.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	O mesmo que inline; a disposição é anexo.	Resposta de download no navegador.	Response	O mesmo que inline.	Use para downloads explícitos.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	O mesmo que inline.	Emite os bytes do PDF materializado em blocos.	StreamedResponse	O mesmo que inline.	Não evita a materialização do documento.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	O mesmo que streamInline; a disposição é anexo.	Resposta de stream de download.	StreamedResponse	O mesmo que streamInline.	Aplique a política de tamanho da saída antes de renderizar.

Messenger

Use esta tabela para o caminho assíncrono: o DTO de mensagem que você despacha, a interface de builder que você implementa e o handler que roda no worker.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])	builderClass: class-string que implementa PdfBuilderInterface; outputPath: .pdf de destino; builderContext: dados serializáveis.	Array de contexto vazio.	DTO de mensagem.	InvalidArgumentException para nome de classe totalmente qualificado (FQCN), stream wrapper, byte nulo, traversal, caminho vazio ou destino não-.pdf inválidos.	Os transportes do Messenger carregam dados, não closures.
PdfBuilderInterface::build(Document $document, array $context): Document	document: documento novo e configurado; context: dados serializáveis da mensagem.	Nenhum contexto padrão além do valor da mensagem.	Objeto Document configurado.	Exceções específicas do builder.	Faça os builders determinísticos e idempotentes.
new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)	Fábrica de PDF e service locator de builders marcados.	Nenhum documento é criado durante a construção.	GeneratePdfHandler	Erros de ligação do container.	O locator deve expor apenas implementações de PdfBuilderInterface.
GeneratePdfHandler::__invoke(GeneratePdfMessage $message)	message: DTO de mensagem validado.	Resolve o builder a partir do container, constrói o documento e o salva.	void	Serviço de builder ausente, resultado de builder inválido, erros de escrita do core.	Prefira builders de serviço a callbacks estáticos.

Notas de desenvolvimento

• Não armazene um Document como um serviço. Armazene PdfFactory e chame create() para cada unidade de trabalho.
• Enfileire apenas contexto serializável. Não coloque streams abertos, closures ou objetos de requisição em builderContext.
• Use uma política de caminho de saída mais rígida que a do DTO quando o deployment tiver raízes de armazenamento específicas por tenant.