Inicialização e descoberta do compat-legacy do NextPDF

Visão geral

nextpdf/compat-legacy expõe NextPDF\Compat\Tcpdf\TCPDF, uma fachada compatível com TCPDF que delega chamadas ao motor do NextPDF. É uma camada de compatibilidade, e não um clone para substituição direta. Ela delega diretamente 94 dos cerca de 120 métodos TCPDF 6.x analisados. Os demais métodos têm diferenças de comportamento documentadas; consulte /integrations/tcpdf-compat/method-coverage/.

Não há nenhuma vinculação global no momento do autoload. Carregar o pacote não cria uma classe global \TCPDF por padrão. Você habilita os aliases globais explicitamente ou, de preferência durante a migração, importa a classe do adaptador por arquivo.

Como a fachada TCPDF é exposta

A fachada é uma classe padrão carregada por autoload de acordo com a PHP Standard Recommendation 4 (PSR-4):

Item	Valor
Classe da fachada	NextPDF\Compat\Tcpdf\TCPDF
Prefixo PSR-4	NextPDF\Compat\Tcpdf\ mapeia para src/Compat/Tcpdf/
Contrato compartilhado	NextPDF\Compat\Contracts\CompatAdapterInterface
Saída de escape	TCPDF::getDocument() retorna o objeto encapsulado NextPDF\Core\Document

A classe intencionalmente não é final. Projetos com TCPDF legado frequentemente criam subclasses de TCPDF para sobrescrever Header() e Footer(), e o adaptador preserva esse ponto de extensão. Internamente, a classe atua como uma fachada. Ela compõe 25 traits de responsabilidade única e delega todas as operações de Portable Document Format (PDF) a uma instância de Document criada quando a fachada é construída.

Sequência de inicialização

Diagram

A construção é a única etapa de “inicialização”. O pacote em si não registra nenhum contêiner de serviços e não realiza nenhuma inicialização de framework. Você adiciona a integração com o framework como uma camada fina; consulte /integrations/tcpdf-compat/integration/.

LegacyDefaults::register() é idempotente: define uma constante apenas quando ela ainda não está definida. As constantes definidas pela aplicação sempre prevalecem se você as definir antes da primeira construção; consulte /integrations/tcpdf-compat/configuration/ § Ordem de resolução da configuração.

Aliases globais de classe opcionais

Se o seu código chama new \TCPDF(...) no namespace global e você ainda não pode alterar esses pontos de chamada, registre os aliases globais uma vez durante a inicialização da aplicação:

examples/boot-aliases.php

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() registra \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS e \TCPDF_IMAGES. tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php verifica esse comportamento:

• É idempotente: chamá-lo duas vezes não lança exceção e registra uma única vez.
• LegacyBootstrap::isRegistered() informa se já foi executado.
• Após o registro, new \TCPDF() cria uma instância do adaptador.

Como evitar conflitos com uma instalação real do TCPDF

Esta é a regra mais importante desta página.

enableAliases() registra um alias somente se nenhuma classe com esse nome já existir (class_exists($alias, autoload: false)). Portanto:

• Se tecnickcom/tcpdf estiver instalado e o \TCPDF dessa instalação carregar primeiro, o alias é ignorado silenciosamente e o seu código continua usando o TCPDF legado, não o adaptador.
• Executar as duas bibliotecas com aliases globais habilitados no mesmo processo não é suportado e produz comportamento ambíguo.

Durante a migração, prefira importações explícitas por arquivo (use NextPDF\Compat\Tcpdf\TCPDF;). Elas são fáceis de encontrar em buscas e não geram ambiguidade. Remova tecnickcom/tcpdf assim que a auditoria em modo estrito passar; consulte /integrations/tcpdf-compat/migration/ Etapa 5. Quando \TCPDF é resolvido para a classe errada, /integrations/tcpdf-compat/troubleshooting/ traz o diagnóstico.

Bindings do contêiner

O pacote não inclui bindings de contêiner de framework. Se você vincular a fachada em um contêiner, vincule uma factory que retorne uma nova NextPDF\Compat\Tcpdf\TCPDF para cada documento. O estado do documento pertence à instância e não deve ser compartilhado entre documentos não relacionados; consulte /integrations/tcpdf-compat/production-usage/ § Concorrência. /integrations/tcpdf-compat/integration/ mostra um binding típico.

Ordem de resolução da configuração

Na construção, o adaptador resolve a configuração nesta ordem: primeiro os argumentos do construtor, depois quaisquer constantes legadas já definidas pela aplicação e, por fim, os padrões de LegacyDefaults referentes ao TCPDF 6.2.13 para qualquer constante que ainda não esteja definida. Para detalhes completos e o objeto moderno AdaptationConfig, consulte /integrations/tcpdf-compat/configuration/.

Diagnóstico

Para confirmar que a fachada está conectada e que o vínculo com o motor está sendo resolvido, construa um adaptador, gere um PDF de uma página e verifique o prefixo %PDF. Os testes de saída do pacote verificam a mesma superfície. A verificação executável está em /integrations/tcpdf-compat/install/ § Verifique a instalação.

Para detectar um conflito com o TCPDF real antes de habilitar os aliases, verifique se um \TCPDF global já existe no ponto em que você chamaria enableAliases(). Se existir, o alias será ignorado. Resolva o conflito com importações explícitas ou remova o TCPDF real antes de depender do adaptador.

Cobertura da API do TCPDF

A matriz de cobertura definitiva e verificada por testes fica no arquivo do repositório docs/TCPDF_COVERAGE.md. O resumo voltado ao leitor, incluindo as listas de métodos ignorados silenciosamente e não implementados, está em /integrations/tcpdf-compat/method-coverage/. Este pacote não afirma ser uma “substituição direta” nem “100% compatível com TCPDF”; é uma alternativa compatível com TCPDF, com uma superfície de compatibilidade conhecida e testada e diferenças de comportamento documentadas.

Consulte também

• docs/TCPDF_COVERAGE.md — fonte de cobertura definitiva (no repositório)
• /integrations/tcpdf-compat/integration/ — conexão da fachada a uma aplicação/framework
• /integrations/tcpdf-compat/method-coverage/ — comportamento por método e lacunas
• /integrations/tcpdf-compat/migration/ — estratégia de migração em etapas
• /integrations/tcpdf-compat/troubleshooting/ — diagnóstico de conflito entre alias e real-TCPDF
• tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — fonte de verdade do comportamento dos aliases