Boot e descoberta do NextPDF no Symfony

Visão geral

O kernel registra o NextPdfBundle. A extensão de Injeção de Dependência (DI) do bundle carrega services.php e transforma a árvore de configuração em parâmetros do container. Em seguida, um compiler pass conecta as extensões opcionais e o aquecimento de fontes.

Como o Symfony Flex reconhece o bundle

O composer.json do bundle declara uma dica de registro automático:

{
    "extra": {
        "symfony": {
            "bundles": {
                "NextPDF\\Symfony\\NextPdfBundle": "all"
            }
        }
    }
}

Em uma aplicação Symfony Flex, essa dica adiciona NextPDF\Symfony\NextPdfBundle ao config/bundles.php para todos os ambientes (all). Sem o Flex, adicione o bundle manualmente em config/bundles.php. A documentação do Symfony descreve o modelo de registro de bundles em (https://symfony.com/doc/current/bundles.html). As classes do bundle são carregadas automaticamente com o prefixo PHP Standard Recommendation (PSR)-4 NextPDF\Symfony\, mapeado para src/Symfony/. Um autoloader PSR-4 mapeia o prefixo de namespace para esse diretório base (PSR-4 §2).

Sequência de boot

A sequência de boot, verificada contra o código-fonte do bundle:

1. O kernel registra os bundles. Kernel::registerBundles() lê config/bundles.php e instancia NextPDF\Symfony\NextPdfBundle, que estende Symfony\Component\HttpKernel\Bundle\Bundle.
2. Build do bundle. NextPdfBundle::build() chama o método pai e, em seguida, registra um compiler pass: OptionalExtensionPass. NextPdfBundle::getPath() retorna a raiz do pacote.
3. Carregamento da extensão. A extensão de DI NextPDF\Symfony\DependencyInjection\NextPdfExtension (alias nextpdf) executa processConfiguration() contra Configuration. Ela armazena os valores resolvidos como parâmetros do container nextpdf.* e depois carrega config/services.php por meio de um PhpFileLoader.
4. Verificação das extensões obrigatórias. NextPdfExtension::load() termina verificando se ext-mbstring e ext-zlib estão presentes, e falha imediatamente caso não estejam.
5. O compiler pass executa. Durante a compilação do container, OptionalExtensionPass::process() configura flags de disponibilidade de extensões em PdfFactory, registra condicionalmente o signer e o cliente da autoridade de carimbo do tempo (TSA), e agenda o aquecimento e o bloqueio do registro de fontes.
6. Container compilado e em cache. O Symfony grava o container compilado. cache:warmup executa esta etapa antes de o tráfego chegar à aplicação.

Compiler passes

O bundle registra exatamente um pass, NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass, em NextPdfBundle::build(). Ele executa no grupo de passes padrão (before-optimization). O pass executa quatro etapas. Cada etapa tem uma guarda, de modo que não faz nada quando suas entradas estão ausentes:

• Flags de extensão — adiciona chamadas de método setArtisanAvailable(...) e setProAvailable(...) à definição de PdfFactory. Os valores vêm de verificações class_exists em tempo de compilação para a fábrica de browser do Artisan e para a classe PDF/A do Pro.
• Registro do signer — registra uma fábrica de informações de certificado e um serviço de signer para o perfil baseline B-B quando nextpdf.signature está presente, enabled é true, e um certificado está definido.
• Cliente TSA — registra um serviço de cliente TSA quando nextpdf.tsa tem um Localizador Uniforme de Recursos (URL).
• Aquecimento de fontes — adiciona chamadas de método warmup() e lock() à definição do registro de fontes quando nextpdf.preload_fonts não está vazio.

Bindings do container

config/services.php define os serviços. O serviço de documento nextpdf.document (com alias para NextPDF\Contracts\PdfDocumentInterface e NextPDF\Core\Document) é não compartilhado: cada resolução retorna um documento novo. A PSR-11 permite explicitamente esse comportamento; chamadas get() sucessivas para um mesmo id podem retornar valores diferentes (PSR-11 §1.1.2). O registro de fontes é compartilhado e bloqueado após o aquecimento. O registro de imagens é compartilhado e marcado com a tag kernel.reset. A tabela completa está em /integrations/symfony/configuration/.

Ordem de resolução da configuração

1. Padrões embutidos de Configuration (getConfigTreeBuilder()).
2. Overrides da aplicação em config/packages/nextpdf.yaml, além de overrides por ambiente em config/packages/<env>/.
3. O Symfony resolve os placeholders de parâmetro %kernel.*%. Por exemplo, fonts_path tem como padrão %kernel.project_dir%/resources/fonts.
4. NextPdfExtension::load() grava o resultado mesclado nos parâmetros do container nextpdf.* que services.php e o compiler pass consomem.

Valores inválidos falham nas etapas 1–2 com uma InvalidConfigurationException do Symfony.

Diagnóstico

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console cache:clear

O primeiro comando lista os serviços registrados. O segundo imprime a configuração mesclada. O terceiro reconstrói o container e executa novamente as verificações de extensão em tempo de compilação.

Conformidade

Cada linha é uma afirmação normativa nesta página, vinculada a um reference_id completo de 64 caracteres hexadecimais do corpus restrito da organização de desenvolvimento de padrões (SDO). A procedência (manifesto do corpus, transporte de recuperação) fica em _sidecars/rag-citations.yaml.

Spec	Cláusula	reference_id	Afirmação
PSR-11	psr_11_container#1.1.2.p3.b		A resolução do container pode diferir a cada chamada
PSR-4	psr_4_autoload#x1.x2.p5		Mapeamento de prefixo de namespace para diretório base

Veja também

• /integrations/symfony/integration/ — referência de conexão de ponta a ponta.
• /integrations/symfony/install/ — instalação e registro.
• /integrations/symfony/configuration/ — árvore de configuração completa e tabela de serviços.
• /integrations/symfony/overview/ — resumo de recursos.