Configuração do compat-legacy

Visão geral

O adaptador expõe três superfícies de configuração:

Modo estrito — uma chave de auditoria que transforma a perda silenciosa de parâmetros em exceções. Ela vem desativada por padrão.
Constantes legadas — as constantes K_* / PDF_* do TCPDF, definidas automaticamente com os padrões do TCPDF 6.2.13 para que o código legado que as lê continue funcionando.
AdaptationConfig — um objeto de configuração moderno e imutável que substitui a configuração baseada em constantes.

Você ainda configura a maior parte das definições do documento pelos métodos do TCPDF que já usa (SetMargins(), SetFont() e assim por diante). As seções a seguir abordam apenas o que é específico da camada de compatibilidade.

Modo estrito

O modo estrito é a configuração principal durante uma migração. Ele não altera a saída renderizada. Ele controla se uma chamada que não consegue reproduzir o comportamento do TCPDF falha explicitamente ou degrada silenciosamente.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();

$pdf->setStrictMode(true);   // audit: throw on silent parameter loss
$isOn = $pdf->isStrictMode(); // true
$pdf->setStrictMode(false);  // back to backward-compatible default

Esses resultados são verificados por tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php:

Modo	Método de ignorar-silenciosamente chamado	Resultado
Desativado (padrão)	por exemplo, `Image()` com parâmetros extras	Executa; os parâmetros ignorados não têm efeito
Ativado	mesma chamada	Lança `TcpdfNotImplementedException` nomeando os parâmetros ignorados
Ativado	um método que ignora silenciosamente chamado apenas com parâmetros suportados	O método não lança (por exemplo, `SetProtection([], 'u', 'o', 0, [])`)

O modo estrito é aditivo. Quando um método aceita um parâmetro, a delegação ainda ocorre; o modo estrito apenas adiciona uma proteção de exceção para os parâmetros descartados. Use-o em um job dedicado de integração contínua (CI) ou em uma execução pontual de auditoria, não em produção. Isso segue o princípio de falhar explicitamente no tratamento de erros do Application Security Verification Standard (ASVS) 5.0 do Open Worldwide Application Security Project (OWASP) (cláusula reference_id registrada no sidecar do RAG): quem chama precisa conseguir observar quando sua intenção não foi atendida.

Não publique código de produção com o modo estrito ativado. Um parâmetro silenciosamente ignorado é um problema de experiência do desenvolvedor, não uma falha em tempo de execução, e uma exceção em um caminho de renderização de produção é pior do que uma saída degradada. Audite, corrija e então desative o modo — consulte /integrations/tcpdf-compat/migration/.

Constantes legadas do TCPDF

O TCPDF legado lê a configuração a partir das constantes K_* e PDF_*. O adaptador as define automaticamente durante a construção apenas se elas ainda não estiverem definidas, usando os padrões do TCPDF 6.2.13. Se a aplicação já define uma constante (por exemplo, um K_PATH_FONTS personalizado), o valor é preservado.

Padrões selecionados (lista completa: src/Compat/Tcpdf/Config/LegacyDefaults.php):

Constante	Padrão	Observação
`PDF_PAGE_FORMAT`	`A4`
`PDF_PAGE_ORIENTATION`	`P`
`PDF_UNIT`	`mm`
`PDF_MARGIN_LEFT` / `RIGHT`	`15`	unidades do usuário
`PDF_MARGIN_TOP`	`27`	unidades do usuário
`PDF_MARGIN_BOTTOM`	`25`	unidades do usuário
`PDF_FONT_NAME_MAIN`	`helvetica`
`PDF_FONT_SIZE_MAIN`	`10`
`K_CELL_HEIGHT_RATIO`	`1.25`
`K_TCPDF_CALLS_IN_HTML`	`false`	reforçada — sempre false; a marcação não pode disparar a execução de PHP
`K_TCPDF_THROW_EXCEPTION_ERROR`	`true`	reforçada — `Error()` sempre lança; nunca `die()`
`K_TIMEZONE`	`UTC`

Duas dessas constantes são fixadas deliberadamente por segurança e não podem ser flexibilizadas por configuração: K_TCPDF_CALLS_IN_HTML é sempre false, e K_TCPDF_THROW_EXCEPTION_ERROR é, na prática, sempre true. Se o código legado depende de qualquer um desses comportamentos legados inseguros, esse código precisa mudar — consulte /integrations/tcpdf-compat/security-and-operations/.

Defina as constantes personalizadas antes da primeira construção do adaptador, normalmente no bootstrap da aplicação:

<?php

declare(strict_types=1);

// Define BEFORE constructing the adapter; the adapter will not override it.
define('PDF_CREATOR', 'My Application');
define('PDF_AUTHOR', 'My Application');

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
// Creator and Author are seeded from your constants.

O objeto moderno AdaptationConfig

Se você não quiser depender de constantes globais, use o objeto de valor de configuração imutável NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Ele é final readonly, e cada campo assume, por padrão, o valor do TCPDF 6.2.13. Você pode construí-lo apenas com os campos que deseja alterar.

Você também pode construí-lo a partir de quaisquer constantes legadas que estejam definidas no momento:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Config\AdaptationConfig;

// Snapshot the currently-defined legacy constants into an object:
$config = AdaptationConfig::fromLegacyConstants();

echo $config->pageFormat;   // 'A4' unless a constant overrides it
echo $config->fontNameMain; // 'helvetica'
echo $config->marginLeft;   // 15.0

AdaptationConfig é o destino de migração da configuração. À medida que você move os pontos de chamada para a API moderna, substitua as consultas a constantes por campos explícitos de AdaptationConfig. A configuração permanece tipada e local, em vez de global.

Ordem de resolução da configuração

Quando o adaptador constrói um documento, ele resolve a configuração nesta ordem. Os passos posteriores não substituem os anteriores:

Argumentos do construtor (orientation, unit, format, …) — precedência máxima para os valores que cobrem.
Constantes legadas preexistentes definidas pela aplicação.
Constantes padrão do TCPDF 6.2.13, definidas automaticamente por LegacyDefaults para qualquer constante ainda não definida.

Os argumentos do construtor unicode, encoding e diskcache são aceitos por compatibilidade de assinatura e não têm efeito. O NextPDF é sempre Unicode e UTF-8, e não mantém cache de páginas em disco. A flag do construtor pdfa também é aceita, mas a conformidade de arquivamento PDF/A requer uma edição comercial (consulte /integrations/tcpdf-compat/security-and-operations/).

Veja também

src/Compat/Tcpdf/Config/LegacyDefaults.php — os padrões de referência das constantes
src/Compat/Tcpdf/Config/AdaptationConfig.php — objeto de configuração moderno
/integrations/tcpdf-compat/migration/ — como remover a configuração das constantes globais
/integrations/tcpdf-compat/security-and-operations/ — as duas flags reforçadas e não configuráveis