Настройка compat-legacy

Краткий обзор

Адаптер поддерживает три способа настройки:

1. Строгий режим — переключатель аудита: при молчаливом отбрасывании параметров он вызывает исключения. По умолчанию он отключён.
2. Устаревшие константы — константы TCPDF K_* / PDF_*, автоматически определяемые со значениями по умолчанию из версии 6.2.13, чтобы устаревший код, читающий их, продолжал работать.
3. AdaptationConfig — современный неизменяемый объект конфигурации, который заменяет настройку через константы.

Большинство настроек документа вы по-прежнему задаёте через уже используемые методы TCPDF (SetMargins(), SetFont() и так далее). В разделах ниже описано только то, что относится к слою совместимости.

Строгий режим

Строгий режим — важная настройка при миграции. Он не меняет результат отрисовки. Он определяет, должен ли вызов, который не может воспроизвести поведение TCPDF, завершаться с явной ошибкой или молча давать ухудшенный результат.

examples/config-strict.php

<?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

Такое поведение проверяется тестами tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php:

Режим	Вызов метода с молчаливым игнорированием	Результат
Отключён (по умолчанию)	например, Image() с дополнительными параметрами	Выполняется; проигнорированные параметры не влияют на результат
Включён	тот же вызов	Выбрасывается TcpdfNotImplementedException с указанием проигнорированных параметров
Включён	метод с молчаливым игнорированием, вызванный только с поддерживаемыми параметрами	Исключение не выбрасывается (например, SetProtection([], 'u', 'o', 0, []))

Строгий режим дополняет существующее поведение. Когда метод поддерживает параметр, вызов всё равно делегируется; строгий режим только добавляет защитное исключение для отброшенных параметров. Используйте его в отдельной задаче непрерывной интеграции (CI) или в разовом аудите, а не в рабочей среде. Это соответствует принципу явного отказа из раздела обработки ошибок Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) 5.0 (значение reference_id зафиксировано в сопроводительном файле RAG): вызывающий код должен видеть, когда его намерение не выполнено.

Не развёртывайте код с включённым строгим режимом. Молча проигнорированный параметр — это проблема удобства разработки, а не сбой во время выполнения, и исключение на пути отрисовки в рабочей среде хуже, чем ухудшенный результат. Проведите аудит, исправьте найденное и отключите режим — см. /integrations/tcpdf-compat/migration/.

Устаревшие константы TCPDF

Устаревший TCPDF читает конфигурацию из констант K_* и PDF_*. Адаптер определяет их автоматически при создании объекта, только если они ещё не определены, используя значения по умолчанию TCPDF 6.2.13. Если ваше приложение уже определило константу (например, собственную K_PATH_FONTS), это значение сохраняется.

Некоторые значения по умолчанию (полный список: src/Compat/Tcpdf/Config/LegacyDefaults.php):

Константа	Значение по умолчанию	Примечание
PDF_PAGE_FORMAT	A4
PDF_PAGE_ORIENTATION	P
PDF_UNIT	mm
PDF_MARGIN_LEFT / RIGHT	15	пользовательские единицы
PDF_MARGIN_TOP	27	пользовательские единицы
PDF_MARGIN_BOTTOM	25	пользовательские единицы
PDF_FONT_NAME_MAIN	helvetica
PDF_FONT_SIZE_MAIN	10
K_CELL_HEIGHT_RATIO	1.25
K_TCPDF_CALLS_IN_HTML	false	усилено — всегда false; разметка не может запустить выполнение PHP-кода
K_TCPDF_THROW_EXCEPTION_ERROR	true	усилено — Error() всегда выбрасывает исключение; никогда не вызывает die()
K_TIMEZONE	UTC

Две константы намеренно зафиксированы из соображений безопасности и не могут быть ослаблены через конфигурацию: K_TCPDF_CALLS_IN_HTML всегда равна false, а K_TCPDF_THROW_EXCEPTION_ERROR фактически всегда равна true. Если устаревший код зависит от любого из этих небезопасных вариантов поведения, его нужно изменить — см. /integrations/tcpdf-compat/security-and-operations/.

Определяйте собственные константы до первого создания адаптера, обычно в коде загрузки приложения:

examples/config-constants.php

<?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.

Современный объект AdaptationConfig

Если вы не хотите полагаться на глобальные константы, используйте неизменяемый объект-значение конфигурации NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Класс объявлен как final readonly, а каждое поле по умолчанию получает значение TCPDF 6.2.13. Вы можете создать объект, указав только те поля, которые хотите изменить.

Вы также можете создать его из устаревших констант, определённых в данный момент:

examples/config-adaptation.php

<?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 — целевая модель для миграции конфигурации. Когда переводите места вызова на современный API, заменяйте обращения к константам явными полями AdaptationConfig. Конфигурация остаётся типизированной и локальной, а не глобальной.

Порядок разрешения конфигурации

Когда адаптер создаёт документ, он разрешает конфигурацию в следующем порядке. Следующие шаги не переопределяют уже найденные значения:

1. Аргументы конструктора (orientation, unit, format, …) — высший приоритет для значений, которые они охватывают.
2. Устаревшие константы, ранее определённые приложением.
3. Константы по умолчанию TCPDF 6.2.13, автоматически определяемые компонентом LegacyDefaults для каждой ещё не определённой константы.

Аргументы конструктора unicode, encoding и diskcache принимаются ради совместимости сигнатуры и не влияют на результат. NextPDF всегда использует Unicode и UTF-8 и не использует дисковый кэш страниц. Флаг конструктора pdfa также принимается, но для соответствия архивному формату PDF/A требуется коммерческая редакция (см. /integrations/tcpdf-compat/security-and-operations/).

См. также

• src/Compat/Tcpdf/Config/LegacyDefaults.php — эталонные значения констант по умолчанию
• src/Compat/Tcpdf/Config/AdaptationConfig.php — современный объект конфигурации
• /integrations/tcpdf-compat/migration/ — перенос конфигурации с глобальных констант
• /integrations/tcpdf-compat/security-and-operations/ — два усиленных ненастраиваемых флага