Configure compat-legacy

At a glance

The adapter gives you three configuration surfaces:

Strict mode — an audit toggle that turns silent parameter loss into exceptions. It is off by default.
Legacy constants — the TCPDF K_* / PDF_* constants, auto- defined with 6.2.13 defaults so legacy code that reads them keeps working.
AdaptationConfig — a modern, immutable configuration object that replaces constant-based configuration.

You still configure most document settings through the TCPDF methods you already call (SetMargins(), SetFont(), and so on). The sections below cover only what is specific to the compatibility layer.

Strict mode

Strict mode is the key setting for a migration. It does not change rendered output. It controls whether a call that cannot reproduce TCPDF behavior fails loudly or degrades silently.

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

These outcomes are asserted by tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php:

Mode	Silent-ignore method called	Result
Off (default)	e.g. `Image()` with extra params	Runs; ignored params have no effect
On	same call	Throws `TcpdfNotImplementedException` naming the ignored params
On	a silent-ignore method called with only supported params	Does not throw (e.g. `SetProtection([], 'u', 'o', 0, [])`)

Strict mode is additive. When a method supports a parameter, delegation still happens; strict mode only adds an exception guard for parameters that are dropped. Use it in a dedicated continuous integration (CI) job or a one-off audit pass, not in production. This follows the fail-explicitly principle from Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) 5.0 error handling (clause reference_id recorded in the RAG sidecar): a caller must be able to observe when its intent was not honored.

Do not ship production code with strict mode on. A silently ignored parameter is a developer experience issue, not a runtime fault, and an exception in a production render path is worse than degraded output. Audit, fix, then turn it off — see /integrations/tcpdf-compat/migration/.

Legacy TCPDF constants

Legacy TCPDF reads configuration from K_* and PDF_* constants. The adapter defines them automatically at construction time only if they are not already defined, using TCPDF 6.2.13 defaults. If your application already defines a constant (for example, a custom K_PATH_FONTS), your value is preserved.

Selected defaults (full list: src/Compat/Tcpdf/Config/LegacyDefaults.php):

Constant	Default	Note
`PDF_PAGE_FORMAT`	`A4`
`PDF_PAGE_ORIENTATION`	`P`
`PDF_UNIT`	`mm`
`PDF_MARGIN_LEFT` / `RIGHT`	`15`	user units
`PDF_MARGIN_TOP`	`27`	user units
`PDF_MARGIN_BOTTOM`	`25`	user units
`PDF_FONT_NAME_MAIN`	`helvetica`
`PDF_FONT_SIZE_MAIN`	`10`
`K_CELL_HEIGHT_RATIO`	`1.25`
`K_TCPDF_CALLS_IN_HTML`	`false`	hardened — always false; markup cannot trigger PHP execution
`K_TCPDF_THROW_EXCEPTION_ERROR`	`true`	hardened — `Error()` always throws; never `die()`
`K_TIMEZONE`	`UTC`

Two of these are deliberately fixed for safety and cannot be relaxed through configuration: K_TCPDF_CALLS_IN_HTML is always false, and K_TCPDF_THROW_EXCEPTION_ERROR is effectively always true. If legacy code depends on either unsafe legacy behavior, that code must change — see /integrations/tcpdf-compat/security-and-operations/.

Define custom constants before the first adapter construction, typically in your application bootstrap:

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

The modern AdaptationConfig object

If you do not want to rely on global constants, use the immutable configuration value object, NextPDF\Compat\Tcpdf\Config\AdaptationConfig. It is final readonly, and every field defaults to the TCPDF 6.2.13 value. You can construct it with only the fields you want to change.

You can also build it from whichever legacy constants are currently defined:

<?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 is the migration target for configuration. As you move call sites onto the modern API, replace constant lookups with explicit AdaptationConfig fields. Configuration stays typed and local rather than global.

Configuration resolution order

When the adapter constructs a document, it resolves configuration in this order. Later steps do not override earlier ones:

Constructor arguments (orientation, unit, format, …) — highest precedence for the values they cover.
Pre-existing application-defined legacy constants.
TCPDF 6.2.13 default constants, auto-defined by LegacyDefaults for any constant not already defined.

Constructor arguments unicode, encoding, and diskcache are accepted for signature compatibility and have no effect. NextPDF is always Unicode and UTF-8, and has no on-disk page cache. The pdfa constructor flag is also accepted, but PDF/A archival conformance requires a commercial edition (see /integrations/tcpdf-compat/security-and-operations/).