TCPDF compatibility API reference

At a glance

The nextpdf/compat-legacy package exposes one main class, NextPDF\Compat\Tcpdf\TCPDF. It mirrors the TCPDF 6.x public application programming interface (API), but renders with the modern NextPDF engine. The package also includes a small support surface: LegacyBootstrap for global class aliases, the AdaptationConfig/LegacyDefaults configuration surface, internal bridge classes for output, construction, color, units, and page formats, and compatibility exceptions. Use it as a migration aid, not a permanent dependency. The method coverage table is the source for complete legacy method status. This page documents only the surfaces application code should depend on intentionally.

Start here: If you are new to this package, construct NextPDF\Compat\Tcpdf\TCPDF, make your usual TCPDF calls (AddPage(), SetFont(), Cell()), and finish with Output($name, $dest). That class is the entry point for almost everything below. For runnable starting points, see Common tasks.

Common tasks

These are the package tasks you will use most often. Each block is verified against the adapter source and runs as-is.

Produce a Portable Document Format (PDF) file with familiar TCPDF calls, then capture it as a string for a queue, an HTTP response, or storage:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetTitle('Invoice 1234');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

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

What it does: Builds a PDF 2.0 document through the TCPDF-shaped adapter. It returns the raw bytes (%PDF...) because destination 'S' routes through OutputBridge to Document::getPdfData() instead of echoing, so it is safe inside a worker or controller.

Register the global aliases once at boot to run existing new \TCPDF(...) code without source edits:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/legacy.pdf', 'F');

What it does: enableAliases() idempotently registers \TCPDF (and the \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES helpers) only when those names are not already defined. Unchanged legacy code then runs on the adapter.

Audit a migration by surfacing every TCPDF parameter the adapter would otherwise drop silently:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter
}

What it does: With setStrictMode(true), a call that cannot reproduce TCPDF behavior throws TcpdfNotImplementedException and names every ignored parameter. This turns silent degradation into a migration work list. Run it during an audit pass only, never in production.

Main adapter

This table is the canonical adapter surface. Use it to find the class you construct (TCPDF), its strict-mode and escape-hatch methods, and the contract it implements.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
NextPDF\Compat\Tcpdf\TCPDF	Constructor parameters follow the legacy TCPDF shape through ConstructorBridge.	Creates an adapter backed by a NextPDF document.	TCPDF	Constructor validation or unsupported-feature exceptions.	Use during migration, not for new native NextPDF code.
TCPDF::getDocument()	none.	Returns the underlying NextPDF document.	NextPDF\Core\Document	none expected.	Use as an escape hatch for migration code that must mix legacy and native calls.
TCPDF::getUnitConverter()	none.	Returns the converter created from the legacy unit.	UnitConverter	none expected.	Use for migration diagnostics, not normal application code.
TCPDF::setStrictMode(bool $enabled)	Strict-mode flag.	Enables or disables explicit failure for unsupported compatibility behavior.	static	none expected.	Keep enabled during migration audits.
TCPDF::isStrictMode()	none.	Returns the current strict-mode flag.	bool	none expected.	Useful in test assertions.
TCPDF legacy methods	Varies by method.	Supported methods map to core document calls; unsupported methods fail explicitly.	Varies by method.	TcpdfNotImplementedException or UnsupportedFeatureException.	Check method coverage before relying on a method.
CompatAdapterInterface::getDocument()	none.	Contract method implemented by TCPDF.	Document	none expected.	Allows tooling to reach the native document.
CompatAdapterInterface::Output(string $name = '', string $dest = '')	Filename and legacy destination.	Delegates to the output bridge.	string	Core write or unsupported-destination errors.	Mirrors legacy TCPDF output; the concrete TCPDF::Output supplies the 'doc.pdf'/'I' defaults.

Legacy method groups

This table maps the TCPDF method families the adapter covers. Scan it to locate a legacy call before you check its exact status in method coverage.

Group	Representative symbols	Default behavior	Notes
Lifecycle and output	Open(), Close(), Output(), getPDFData()	Maintains a TCPDF-shaped document lifecycle over a native document.	Prefer native output APIs after migration.
Metadata	SetTitle(), SetAuthor(), SetSubject(), SetKeywords(), SetCreator()	Maps metadata setters to the underlying document.	Keep metadata normalization in application code.
Pages and positioning	AddPage(), setPage(), lastPage(), GetX(), SetXY()	Converts legacy units and coordinates to native page operations.	Verify absolute positioning visually after migration.
Margins and layout	SetMargins(), SetAutoPageBreak(), setCellPaddings(), getMargins()	Stores compatibility state and maps supported values.	Complex TCPDF page-break behavior may require manual review.
Fonts and text	SetFont(), AddFont(), Cell(), MultiCell(), Write(), Text()	Routes common text operations to native font and text APIs.	Check CJK and encoding behavior with production fonts.
HTML	writeHTML(), writeHTMLCell(), fixHTMLCode()	Passes supported HTML to the native HTML pipeline.	The native renderer is not a full TCPDF HTML clone.
Images and drawing	Image(), Line(), Rect(), Circle(), SetDrawColor()	Maps supported graphics operations through adapter concerns.	Unsupported vector or special formats fail explicitly.
Navigation and annotations	Bookmark(), AddLink(), SetLink(), Annotation()	Preserves common navigation calls where mapped.	Validate generated outlines and links.
Security and signatures	SetProtection(), setSignature(), setTimeStamp(), setUserRights()	Bridges supported legacy security calls to native features.	Treat cryptographic output as a separate verification gate.
Forms, templates, transforms	TextField(), startTemplate(), StartTransform(), Rotate(), Scale()	Implements supported subsets and fails loudly for unsupported behavior.	Audit each call against method coverage before rollout.

Bootstrap and configuration

Use this table when you wire the adapter into an application boot path, register global aliases, or choose between legacy constants and the modern AdaptationConfig.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
LegacyBootstrap::enableAliases()	none.	Registers compatibility aliases once.	void	Autoload or environment errors.	Use only when legacy code expects TCPDF names to exist globally.
LegacyBootstrap::isRegistered()	none.	Reports whether aliases have been registered.	bool	none expected.	Useful in bootstrap tests.
LegacyBootstrap::resetForTesting()	none.	Clears registration state for tests.	void	none expected.	Test-only helper.
AdaptationConfig	Adapter flags and migration controls.	Uses package defaults when omitted.	AdaptationConfig	Invalid option values.	Keep config explicit during migration audits.
AdaptationConfig::fromLegacyConstants()	none.	Reads known legacy constants and builds a config object.	AdaptationConfig	Invalid legacy constant values.	Transitional helper for large legacy applications.
LegacyDefaults	none.	Provides default legacy values.	Default values.	none expected.	Central place for compatibility defaults.

Bridges and helpers

These internal conversion classes power the adapter. Use this table when you contribute adapter coverage or diagnose how a legacy argument was translated. For everyday application code, prefer the public adapter surface.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
ConstructorBridge	Legacy constructor argument list.	Normalizes legacy options into NextPDF config.	Constructor data.	Invalid legacy argument values.	Used internally by the adapter.
CellParameterAdapter	TCPDF cell parameters.	Maps legacy positional arguments to core text layout options.	Adapted parameters.	Invalid dimensions or alignment.	Prefer native core methods in new code.
OutputBridge::dispatch(Document $document, string $filename, string $dest)	Native document, filename, and legacy destination.	Maps inline/download/save behavior to NextPDF output APIs.	string	Core write errors; unsupported destination.	Validate filenames and storage roots before output.
OutputBridge::resolveDestination(string $dest)	Legacy destination code.	Converts destination to a native output destination.	OutputDestination	Unsupported destination errors.	Keeps destination mapping centralized.
ColorTranslator	TCPDF color arguments.	Normalizes legacy color forms.	Core color value.	Invalid color values.	Used by color and drawing concerns.
PageFormatResolver	Legacy page format input.	Maps known names to core page sizes.	Page format value.	Unknown format.	Use explicit native page sizes after migration.
UnitConverter	Legacy measurement values and units.	Converts to core units.	Numeric value.	Invalid unit.	Helps preserve legacy layout behavior.

Exceptions

Use this table when a migration call fails loudly. It separates “not implemented” from “known but unsupported” failures and shows the recovery path.

Symbol	Meaning	Recovery
TcpdfNotImplementedException	The adapter intentionally does not implement the requested legacy method.	Replace the call with the native NextPDF API or remove the dependency.
TcpdfNotImplementedException::forSilentIgnore()	A legacy call would previously have been ignored but is surfaced for migration clarity.	Decide whether explicit no-op behavior is acceptable.
TcpdfNotImplementedException::forUnimplemented()	A legacy call has no implemented adapter path.	Replace the call or isolate it behind migration code.
UnsupportedFeatureException	The legacy feature is known but not supported under the adapter boundary.	Check migration guidance and isolate the feature behind an application adapter.
UnsupportedFeatureException::forMethod()	Creates a method-specific unsupported-feature error.	Use in compatibility contributions to preserve consistent failure messages.

Development notes

• Treat the adapter as a migration tool. New code should target core NextPDF APIs directly.
• Unsupported behavior should fail loudly. Do not catch compatibility exceptions and continue with a partial document unless the application explicitly accepts that risk.
• Keep migration changes small and verify each legacy method against the coverage table.