Integração do NextPDF com o Symfony

Visão geral

Instale o nextpdf/symfony, deixe o Flex registrar o bundle ou registre-o manualmente, adicione config/packages/nextpdf.yaml e injete o PdfFactory. Use esta página como índice da integração. Cada etapa aponta para um guia mais aprofundado.

Instalação

composer require nextpdf/symfony

O bundle requer nextpdf/core^3.0 || ^5.2, symfony/*^7.2 e psr/log^3.0. O autoload das classes usa o prefixo PHP Standards Recommendation (PSR)-4 NextPDF\Symfony\, mapeado para src/Symfony/. Um autoloader PSR-4 mapeia esse prefixo de namespace para o diretório base (PSR-4 §2). Para conhecer todos os requisitos e os pacotes opcionais, consulte /integrations/symfony/install/.

Inicialização e descoberta automática

Com o Symfony Flex, a entrada extra.symfony.bundles no composer.json do bundle registra o NextPDF\Symfony\NextPdfBundle em todos os ambientes. Sem o Flex, adicione-o manualmente ao config/bundles.php:

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

Para a sequência completa de inicialização e o comportamento do compiler pass, consulte /integrations/symfony/boot-and-discovery/.

Vínculos do container

O arquivo config/services.php do bundle registra os seguintes serviços:

Serviço / alias	Ciclo de vida
`NextPDF\Symfony\Service\PdfFactory`	compartilhado, público; injete este
`nextpdf.document` → `PdfDocumentInterface` → `Document`	não compartilhado, público; nova instância a cada resolução
`NextPDF\Contracts\FontRegistryInterface`	compartilhado, bloqueado após o aquecimento
`NextPDF\Graphics\ImageRegistry`	compartilhado, `kernel.reset`
`NextPDF\Contracts\DocumentFactoryInterface`	compartilhado
`NextPDF\Symfony\Http\PdfResponse`	helper público e sem estado

O vínculo do documento é deliberadamente não compartilhado. O PSR-11 permite que um container retorne valores diferentes em chamadas get() sucessivas para o mesmo identificador. Criar um documento novo evita o compartilhamento de estado entre requisições em workers de longa duração (PSR-11 §1.1.2). Para ver a tabela completa de serviços e aliases, incluindo os vínculos condicionais de EInvoice, consulte /integrations/symfony/configuration/.

Publicar a configuração

O alias de configuração é nextpdf. Crie config/packages/nextpdf.yaml. Ao publicar uma recipe, o Flex adiciona uma cópia padrão para você. Toda chave tem um valor padrão, portanto um arquivo mínimo fica assim:

nextpdf: ~

A árvore completa de configuração está documentada em /integrations/symfony/configuration/.

Primeiro uso

Injete o PdfFactory e, em seguida, retorne o documento com 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');
    }
}

Para ver o controller completo e o fluxo assíncrono com o Messenger, consulte /integrations/symfony/quickstart/.

Teste de fumaça do bundle

Verifique a integração sem escrever código da aplicação:

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

debug:container nextpdf deve listar o PdfFactory, o alias nextpdf.document e os registries. O lint:container verifica se todos os argumentos dos serviços são resolvidos. Para testar a geração, adicione o controller acima e, em seguida, faça uma requisição para /hello.pdf.

Pontos de entrada da API pública

A superfície da API expõe estes símbolos públicos para o código da aplicação:

Símbolo	Finalidade
`NextPDF\Symfony\Service\PdfFactory::create()`	novo e pré-configurado `Document`
`NextPDF\Symfony\Http\PdfResponse::inline()` / `download()`	resposta em buffer com cabeçalhos de segurança
`NextPDF\Symfony\Http\PdfResponse::streamInline()` / `streamDownload()`	resposta transmitida em blocos (chunked)
`NextPDF\Symfony\Message\GeneratePdfMessage`	objeto de transferência de dados (DTO) de geração assíncrona (validado)
`NextPDF\Symfony\Message\PdfBuilderInterface`	contrato de builder resolvido pelo handler

Conformidade

Cada linha lista uma afirmação normativa presente nesta página. Cada afirmação está vinculada a um reference_id completo de 64 caracteres hexadecimais do corpus restrito da organização de desenvolvimento de normas (SDO). A proveniência (manifesto do corpus e transporte da recuperação) está em _sidecars/rag-citations.yaml.

Especificação	Cláusula	reference_id	Afirmação
PSR-11	`psr_11_container#1.1.2.p4`		Contrato de identificador has()/get() do container
PSR-4	`psr_4_autoload#x1.x2.p5`		Mapeamento de namespace do autoloader

Veja também

/integrations/symfony/install/ — requisitos e registro.
/integrations/symfony/boot-and-discovery/ — descoberta, inicialização e compiler pass.
/integrations/symfony/configuration/ — schema completo e tabela de serviços.
/integrations/symfony/quickstart/ — controller executável e exemplo assíncrono.
/integrations/symfony/production-usage/ — segurança de workers e streaming.