Visão geral da integração do NextPDF com Symfony

Visão geral

nextpdf/symfony é o bundle oficial Symfony 7 para o engine NextPDF. Ele conecta o engine ao container do Symfony e fornece uma fábrica de documentos para você injetar nos seus próprios serviços. Ele também inclui helpers para respostas Hypertext Transfer Protocol (HTTP) e um caminho de geração assíncrona de arquivos Portable Document Format (PDF), para que o trabalho possa ser executado em segundo plano.

O que o bundle oferece

O NextPDF Symfony integra o engine nextpdf/core a uma aplicação Symfony na forma de um bundle padrão. Ele adiciona estes blocos de construção, cada um conferido no código-fonte do bundle em src/Symfony/:

• Um ponto de entrada do bundle — NextPDF\Symfony\NextPdfBundle estende a classe base Bundle do Symfony e registra um compiler pass.
• Uma extensão de injeção de dependências — NextPDF\Symfony\DependencyInjection\NextPdfExtension carrega as definições de serviço, converte a árvore de configuração em parâmetros do container e expõe o alias de configuração nextpdf.
• Uma árvore de configuração tipada — NextPDF\Symfony\DependencyInjection\Configuration define o schema de configuração nextpdf. Ela valida valores de enum, define valores padrão e usa placeholders de parâmetro %kernel.*%.
• Uma fábrica de documentos injetável — NextPDF\Symfony\Service\PdfFactory produz novas instâncias NextPDF\Core\Document pré-configuradas. É o equivalente, no Symfony, a uma facade estática.
• Helpers de resposta HTTP — NextPDF\Symfony\Http\PdfResponse constrói respostas inline, para download e em streaming com um conjunto fixo de cabeçalhos de segurança alinhados ao Open Worldwide Application Security Project (OWASP).
• Um caminho de geração assíncrona — NextPDF\Symfony\Message\GeneratePdfMessage, NextPDF\Symfony\Message\GeneratePdfHandler e NextPDF\Symfony\Message\PdfBuilderInterface integram-se ao Symfony Messenger para que a renderização de PDF possa ser executada em um worker.
• Um detector de extensões em tempo de compilação — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass detecta extensões NextPDF opcionais e registra seus serviços somente quando essas extensões estão presentes.

Contrato do container

O bundle registra um conjunto pequeno e estável de serviços públicos do container. O serviço de documento nextpdf.document (com aliases para NextPDF\Contracts\PdfDocumentInterface e NextPDF\Core\Document) não é compartilhado: cada resolução do serviço retorna um documento distinto e descartável. Isso corresponde ao contrato de container da PHP Standard Recommendation 11 (PSR-11): duas chamadas sucessivas a get() com o mesmo identificador podem retornar valores diferentes dependendo da configuração do container — veja PSR-11 §1.1.2. O binding não compartilhado é intencional. Um documento acumula estado durante a renderização, então uma nova instância por requisição evita que o estado vaze entre requisições em workers de longa duração.

O registro de fontes (NextPDF\Contracts\FontRegistryInterface) segue o caminho oposto: é um singleton compartilhado. O registro de imagens recebe a tag kernel.reset, para que seu cache limitado seja limpo entre requisições em workers FrankenPHP e Messenger. A página de configuração documenta a tabela completa de serviços e aliases.

Logging opcional

Os registros de fontes e de imagens aceitam um logger PHP Standard Recommendation 3 (PSR-3) opcional. O bundle faz o binding de Psr\Log\LoggerInterface somente quando a aplicação fornece um logger (nullOnInvalid()). Portanto, o logging é um colaborador opcional, não uma dependência obrigatória. Isso é consistente com o contrato de logger da PSR-3, em que um logger é um colaborador injetado e substituível (PSR-3).

Recursos core versus opcionais

O bundle em si é software core sob Apache-2.0. Alguns recursos ficam disponíveis somente quando você instala um pacote opcional junto com o bundle:

Recurso	Requer	Detecção
Geração de PDF, PdfFactory, PdfResponse	somente core	sempre disponível
Geração assíncrona	symfony/messenger	o handler é ativado quando o Messenger está instalado
Renderização de HTML via Chrome DevTools Protocol (CDP)	nextpdf/artisan	sonda com class_exists em tempo de compilação
Arquivamento PDF/A, assinaturas digitais	nextpdf/premium (instala o Pro)	sonda com class_exists em tempo de compilação

Quando o nextpdf/premium está instalado, o bundle pode aplicar uma configuração baseline de assinatura PDF Advanced Electronic Signatures (PAdES) B-B. Perfis de assinatura superiores estão fora do escopo da documentação deste bundle. Para a matriz de edições, consulte a documentação do NextPDF Premium.

Quando usar este bundle

Use o nextpdf/symfony quando você gera PDFs em uma aplicação HTTP Symfony 7 ou em um worker. O bundle fornece serviços gerenciados pelo container, registros seguros para workers e respostas de download seguras, de modo que você não precise conectar o engine manualmente. Se você precisa apenas de uma geração pontual em um script, o pacote core nextpdf/core sozinho já é suficiente.

Conformidade

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

Spec	Cláusula	reference_id	Afirmação
PSR-11	psr_11_container#1.1.2.p3.b		Contrato de valor de retorno de get() do container
PSR-3	psr_3_logger#x3.p17		Dependência opcional de LoggerInterface

Contexto comercial

Assinaturas digitais e arquivamento PDF/A ficam disponíveis quando o nextpdf/premium (Pro) é instalado junto com o bundle. Esse recurso Pro opcional não exige alteração de código no bundle Core documentado aqui. Veja </get-license/?intent=symfony-pro>.

Veja também

• /integrations/symfony/install/ — instale e registre o bundle.
• /integrations/symfony/configuration/ — a árvore de configuração nextpdf completa e a tabela de serviços.
• /integrations/symfony/quickstart/ — um controller executável e um exemplo assíncrono.
• /integrations/symfony/boot-and-discovery/ — como o Symfony descobre e inicializa o bundle.
• /integrations/symfony/production-usage/ — segurança de workers, streaming e padrões assíncronos.