Boot e descoberta do NextPDF no CodeIgniter

Visão geral

O CodeIgniter 4 descobre a classe Services do pacote, as funções de helper e o registrar por meio da descoberta de pacotes do Composer. Esta página explica o fluxo e a configuração que controlam essa descoberta.

Como funciona a descoberta de Services do CodeIgniter

O CodeIgniter 4 resolve um service ao examinar cada classe Config\Services descoberta em busca de um método estático que corresponda ao nome do service solicitado. Quando a aplicação chama service('pdf'), o framework encontra a primeira classe Services descoberta que declara um método pdf e então o executa.

A descoberta é governada por Config\Modules:

• $enabled — chave principal para a descoberta automática. Padrão true.
• $discoverInComposer — estende a descoberta aos pacotes do Composer. Padrão true. Essa flag permite que o framework encontre nextpdf/codeigniter.
• $composerPackages — um filtro only / exclude opcional para o conjunto de pacotes do Composer.
• $aliases — os tipos de elementos que participam da descoberta. O padrão do framework inclui services e registrars, e este pacote usa os dois.

A classe do pacote é NextPDF\CodeIgniter\Config\Services. O Composer mapeia o prefixo PHP Standards Recommendation 4 (PSR-4) NextPDF\CodeIgniter\ para src/CodeIgniter/. Um nome de classe totalmente qualificado deve ter um namespace de nível superior (PSR-4 §x1.x2.p5, modal MUST). O prefixo do namespace mapeia para o diretório base, de modo que a classe seja resolvida para o arquivo correspondente (PSR-4 §x1.x3).

Sequência de boot

1. Autoload do Composer. O Composer registra o mapa PSR-4 e as entradas de autoload files. Nesse momento, ele carrega o arquivo helper src/CodeIgniter/Helpers/pdf_helper.php.
2. Bootstrap do framework. O CodeIgniter lê Config\Modules. Quando a descoberta está habilitada, ele monta a lista de elementos descobertos em todos os pacotes do Composer.
3. Descoberta do registrar. O framework coleta as classes Registrar. O Registrar::Autoload() do pacote anuncia o helper pdf ao carregador de helpers do CodeIgniter.
4. Resolução do service na primeira chamada. As factories de service usam lazy loading. A primeira chamada a service('pdf') ou Services::pdf() executa a factory. Os services compartilhados ficam em cache no locator durante o processo.

Bindings do container

O CodeIgniter 4 não fornece um container PSR-11. Em vez disso, os métodos estáticos de factory da classe Services fazem o papel dos bindings. Cada método aceita um parâmetro bool $getShared:

Service	Compartilhado por padrão	Notas
fontRegistry	sim	Pré-aquecido e, em seguida, bloqueado.
imageRegistry	sim	Cache limitado no padrão least recently used (LRU).
documentFactory	sim	Sem estado.
pdfDocument	não	Nova instância a cada chamada.
pdf	não	Nova instância a cada chamada.
tsaClient	sim	null quando nenhuma URL de Time-Stamp Authority (TSA) está configurada.
pdfSigner	não	null quando a assinatura está desabilitada.

As instâncias compartilhadas ficam no cache de instâncias BaseService do CodeIgniter durante o processo. O harness de testes do framework limpa esse cache com BaseService::reset(), e os testes funcionais do pacote dependem desse reset entre os casos.

Ordem de resolução da configuração

A configuração efetiva é resolvida nesta ordem:

1. Padrões do pacote em NextPDF\CodeIgniter\Config\NextPdf.
2. Uma classe da aplicação Config\NextPdf que estende a classe do pacote, quando presente. O CodeIgniter a carrega no lugar do padrão do pacote.
3. Overrides de ambiente aplicados por BaseConfig, indexados pelo nome curto da classe em minúsculas nextpdf (chaves aninhadas com ponto ou a forma totalmente qualificada da classe).

O arquivo de extensão de configuração da aplicação declara uma classe e não tem efeitos colaterais. Isso o mantém alinhado com a expectativa da PSR-1 de que um arquivo declare símbolos ou execute lógica com efeitos colaterais, mas nunca ambos (PSR-1 §x1.x1.p3). O arquivo helper é a contraparte deliberada com efeitos colaterais. Ele declara as funções globais pdf() e pdf_document(), e cada uma é protegida por uma verificação function_exists, de modo que um carregamento duplo seja seguro.

Diagnóstico

• composer dump-autoload — reconstrói o mapa PSR-4 e a lista de autoload files após uma atualização.
• Para verificar a descoberta rapidamente, use um controller que chame Services::pdfDocument(false) e confirme um retorno Document.
• Inspecione vendor/composer/autoload_files.php para confirmar que o arquivo helper está registrado.
• Consulte /integrations/codeigniter/troubleshooting/ para o mapeamento entre falha e causa.

Conformidade

• Um nome de classe totalmente qualificado requer um namespace de nível superior (PSR-4 Autoloader §x1.x2.p5).
• Mapeamento do prefixo do namespace para o caminho da classe no diretório base (PSR-4 Autoloader §x1.x3).
• Um arquivo declara símbolos ou causa efeitos colaterais — o design do arquivo helper (PSR-1 Basic Coding Standard §x1.x1.p3).

Veja também

• /integrations/codeigniter/integration/ — a referência de integração e o smoke test.
• /integrations/codeigniter/install/ — instale e verifique a descoberta.
• /integrations/codeigniter/overview/ — a superfície completa da application programming interface (API).
• /integrations/codeigniter/troubleshooting/ — modos de falha da descoberta.