Integração compat-legacy com o NextPDF

Visão geral

Use nextpdf/compat-legacy para conectar uma aplicação de forma que o código TCPDF 6.x existente rode no motor do NextPDF. O pacote é um auxílio de migração, não uma camada de compatibilidade permanente — remova-o depois de adotar a interface de programação de aplicações (API) moderna (consulte /integrations/tcpdf-compat/migration/). Ele é uma alternativa compatível com TCPDF, não um clone para substituição direta: 94 dos cerca de 120 métodos TCPDF avaliados delegam diretamente. Os métodos restantes têm diferenças de comportamento documentadas (consulte /integrations/tcpdf-compat/method-coverage/).

Instalação

composer require nextpdf/compat-legacy:^3.0

Isso resolve nextpdf/core ^3.0 de forma transitiva. Para ver os requisitos completos e uma verificação de conferência, consulte /integrations/tcpdf-compat/install/.

Inicialização e descoberta automática

O pacote não conecta variáveis globais durante o autoload. Incluí-lo via require não cria um \TCPDF global. Você escolhe como os pontos de chamada resolvem a classe:

Recomendado (importações explícitas). Atualize as linhas use/require para use NextPDF\Compat\Tcpdf\TCPDF; em cada arquivo. Isso é inequívoco e fácil de encontrar em buscas.
Aliases globais opcionais. Chame LegacyBootstrap::enableAliases() uma vez na inicialização para registrar \TCPDF e as quatro classes auxiliares — apenas se esses nomes ainda não estiverem em uso. O mecanismo, a idempotência e a regra de conflito com o TCPDF real estão em /integrations/tcpdf-compat/boot-and-discovery/.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

// One call at application bootstrap, before any \TCPDF use.
LegacyBootstrap::enableAliases();

Bindings de contêiner

O pacote não inclui um service provider nem um bundle de framework. A camada fina de integração fica sob sua responsabilidade. Vincule uma factory que retorne um adaptador novo para cada documento — nunca um singleton compartilhado, porque cada instância mantém o estado do documento (consulte /integrations/tcpdf-compat/production-usage/ § Concurrency).

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use Psr\Container\ContainerInterface;

// Pseudocode for a PSR-11-style container: bind a factory, not a shared instance.
$container->set(TCPDF::class, static function (ContainerInterface $c): TCPDF {
    return new TCPDF('P', 'mm', 'A4');
});

// Each resolution is an independent document context.
$pdf = $container->get(TCPDF::class);

No Symfony, registre a factory como um serviço não compartilhado. No Laravel, use bind (não singleton) para que cada resolução receba uma nova instância. O pacote em si permanece agnóstico ao framework.

Publicar configuração

Não há arquivo de configuração de framework para publicar. Configure o adaptador por meio das constantes legadas K_* / PDF_* (defina-as na inicialização antes da primeira construção) ou por meio do objeto imutável moderno NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Consulte /integrations/tcpdf-compat/configuration/.

Teste de fumaça do service provider / bundle

Depois de conectar tudo, verifique se a integração produz um arquivo Portable Document Format (PDF) válido. Isso espelha a superfície validada por tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Integration smoke test');

$bytes = $pdf->Output('smoke.pdf', 'S');

assert(str_starts_with($bytes, '%PDF'), 'Integration smoke test failed');
echo "Integration OK\n";

Em um contexto de Hypertext Transfer Protocol (HTTP) ou worker, use Output(..., 'F') ou 'S'. Não dependa do caminho inline. Para ver a orientação operacional completa, consulte /integrations/tcpdf-compat/production-usage/.

Pontos de entrada da API pública

Ponto de entrada	Finalidade
`NextPDF\Compat\Tcpdf\TCPDF`	Fachada compatível com TCPDF. Crie uma por documento.
`TCPDF::getDocument()`	Retorna o `NextPDF\Core\Document` encapsulado — a saída de emergência para a API moderna.
`TCPDF::setStrictMode(bool)`	Chave de auditoria de migração (consulte /integrations/tcpdf-compat/configuration/).
`NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()`	Aliases opcionais de classes globais.
`NextPDF\Compat\Tcpdf\Config\AdaptationConfig`	Objeto de configuração imutável moderno.
`NextPDF\Compat\Contracts\CompatAdapterInterface`	Contrato de compatibilidade compartilhado.

Cobertura da API do TCPDF

A matriz de cobertura oficial, verificada por testes, fica no arquivo do repositório docs/TCPDF_COVERAGE.md. O resumo voltado ao leitor — métodos espelhados, ignorados silenciosamente, não implementados e não aplicáveis — está em /integrations/tcpdf-compat/method-coverage/. Não a chame de “substituição direta” nem de implementação “100% compatível”. Descreva-a como uma alternativa compatível com TCPDF, com uma superfície conhecida, testada e com diferenças de comportamento documentadas.

Veja também

docs/TCPDF_COVERAGE.md — fonte de cobertura oficial no repositório
/integrations/tcpdf-compat/boot-and-discovery/ — exposição da fachada e comportamento de aliases
/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/production-usage/ — como executar o adaptador sob carga
tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — referência de comportamento de saída