README

The next generation of TCPDF - a modern, modular PHP library for programmatically generating PDF documents.

If this project is useful to you, please consider supporting development via GitHub Sponsors.

Overview
Description
For TCPDF Users
Features
Requirements
Installation
Font Setup
Quick Start
PDF Import
Remote Resources and fileOptions
Digital Signatures
PDF/X Conformance
PDF/UA Accessibility
Development
Packaging
Contributing
Third-Party Fonts
ICC Profile
Contact

Overview

tc-lib-pdf is a pure-PHP library for dynamically generating PDF documents.
It is the modern evolution of the widely used TCPDF library, redesigned around a modular package architecture, Composer-first workflow, and strict PHP type safety.

It coordinates specialized companion packages for fonts, images, graphics, pages, filtering, and encryption into a cohesive document-authoring API. The result is a production-ready toolkit for invoices, reports, labels, and other generated PDFs where predictable output and long-term maintainability matter.


Namespace	`\Com\Tecnick\Pdf`
Author	Nicola Asuni <info@tecnick.com>
License	GNU LGPL v3 — see LICENSE
Website	https://tcpdf.org
API docs	https://tcpdf.org/docs/srcdoc/tc-lib-pdf
Packagist	https://packagist.org/packages/tecnickcom/tc-lib-pdf

Releases follow Semantic Versioning:

PATCH — backwards-compatible bug fixes
MINOR — backwards-compatible new features
MAJOR — breaking changes

Description

tc-lib-pdf is a modern PDF generation library for PHP applications that need deterministic document output without delegating rendering to an external service. It builds on the long-standing ideas behind TCPDF, but reshapes them into a cleaner, Composer-native package designed for contemporary PHP development.

For teams already familiar with TCPDF, this project offers a more modular foundation with stronger typing, clearer package boundaries, and an API surface intended to be easier to maintain in large codebases. For teams adopting it fresh, it provides a practical way to generate production PDFs directly from PHP while retaining fine-grained control over layout, typography, graphics, metadata, and standards-oriented output.

The library is particularly well suited to backend-driven document workflows such as invoices, shipping labels, statements, certificates, reports, and archived business records. Instead of treating PDF generation as an opaque export step, tc-lib-pdf exposes the document model in a way that lets developers compose pages programmatically, integrate with existing application data, and keep output logic versioned alongside the rest of the codebase.

Because it is part of the broader tc-lib-* ecosystem, tc-lib-pdf can coordinate fonts, images, page geometry, graphics primitives, and optional features such as barcodes and encryption through dedicated companion packages. That modular design makes the project easier to evolve over time while still delivering the all-in-one capabilities PHP developers expect from a serious PDF engine.

For TCPDF Users

If you already know TCPDF, tc-lib-pdf will feel familiar in purpose but it is not positioned as a drop-in replacement.

The codebase is split across focused Composer packages instead of a single monolithic distribution.
The API surface is more strongly typed and organized around companion services such as fonts, pages, graphics, and images.
Setup is Composer-first, which means asset preparation such as font generation is part of project bootstrap rather than an implicit bundled step.

The fastest way to evaluate the library is to follow the installation and font setup steps below, then compare the runnable examples in examples/index.md with the equivalent workflows you already maintain in TCPDF.

Features

Text & Fonts

Full UTF-8 Unicode and right-to-left (RTL) language support
TrueTypeUnicode, OpenTypeUnicode v1, TrueType, OpenType v1, Type1, and CID-0 fonts
Font subsetting to keep file sizes small
Text hyphenation, stretching, and letter-spacing (tracking)
Language-aware TeX hyphenation patterns and optional zero-width breakpoints
Text rendering modes: fill, stroke, and clipping
Automatic line breaks, page breaks, and justification

Layout & Content

All standard page sizes, custom formats, custom margins, and configurable units of measure
HTML and CSS rendering
SVG rendering
Multi-column layouts and no-write page regions
Headers, footers, and common page content
Bookmarks, named destinations, and table of contents
Automatic page numbering and page groups
Full page box control (Media/Crop/Bleed/Trim/Art), page reordering, and viewer preferences

Images & Graphics

Native JPEG, PNG, and SVG support
Extended image format handling via GD (GD, GD2, GD2PART, GIF, JPEG, PNG, BMP, XBM, XPM, WBMP, TIFF, ICO, PSD, IFF, SWC)
Geometric graphics and 2D transformations
Linear and radial gradients, Coons patch mesh gradients, crop marks, and registration bars
JPEG and PNG ICC profiles, grayscale/RGB/CMYK/spot colors, transparencies, and overprint control

Security & Standards

Password and certificate-based document encryption (RC4 and AES, up to 256-bit)
Digital signatures — detached CMS (PKCS#7) signatures with configurable appearance fields
RFC 3161 TSA timestamps — embed a trusted timestamp token from any RFC 3161-compliant Time Stamping Authority (TSA) into the CMS signature; configurable digest algorithm (sha256, sha384, sha512), policy OID, nonce, timeout, and TLS peer verification
LTV (Long-Term Validation) — embed revocation evidence in the same PDF revision as the signature:
- collects the signing certificate chain and fetches OCSP responses and/or CRL payloads from AIA and CDP URLs
- deduplicates binary payloads by fingerprint
- emits /DSS, /VRI, /OCSPs, /CRLs, and /Certs objects in the catalog
- each feature (OCSP, CRL, cert embedding, DSS, VRI) can be enabled independently via setSignature() LTV options
PDF annotations: links, text notes, file attachments, markup, shapes, media, and widgets
JavaScript embedding
PDF/A (1/2/3, including a/b/u conformance levels) — see Factur-X / ZUGFeRD below
PDF/X (generic alias, PDF/X-1a, PDF/X-3, PDF/X-4, PDF/X-5) — print-exchange conformance: per-variant OutputIntent identifiers, GTS_PDFXVersion in Info dict and XMP, PDF version enforcement, CMYK color forcing for restrictive profiles (X-1a, X-3), transparency restrictions, and suppression of encryption and JavaScript
PDF/UA (generic alias, PDF/UA-1, PDF/UA-2) — accessibility conformance: tagged structure tree (StructTreeRoot / ParentTree), MarkInfo /Marked true, document language (/Lang), DisplayDocTitle true, ActualText for ligatures and special glyphs, figure alt-text tagging, and heading-level clamping to prevent skipped levels; PDF/UA-2 targets PDF 2.0

PDF Import

Import pages from existing PDFs as Form XObjects and place them on any destination page
Import a single page at a user-defined position and scale (importPage / useImportedPage)
Append full documents page-by-page, auto-sized to the source page dimensions (addPageFromImport)
Load source PDFs from a file path or raw byte string (setImportSourceFile / setImportSourceData)

Other

1D and 2D barcodes via tc-lib-barcode
Interactive AcroForm fields (buttons, checkboxes, radio buttons, text, combo boxes, list boxes)
XObject templates and layers with object visibility controls
Multiple output targets: inline display, forced download, file save, and MIME attachment
Factur-X / ZUGFeRD workflows via embedded XML in PDF/A-3 documents
Page compression via the zlib PHP extension

Requirements

PHP 8.1 or later
Required PHP extensions: date, pcre (enforced by Composer)
Composer

Optional PHP extensions for extended functionality: gd, zlib.

Feature-specific prerequisites:

Digital signatures, timestamps, and LTV workflows require signing certificates/keys and any external TSA or revocation endpoints your configuration references.
make preflight depends on external validation tools when you want standards validation beyond the built-in sample generation.

Installation

For a clean first run:

Install the package with Composer.
Generate the companion font files.
Run the minimal script using the generated K_PATH_FONTS path.

composer require tecnickcom/tc-lib-pdf

Or add to your composer.json:

{
    "require": {
        "tecnickcom/tc-lib-pdf": "^8"
    }
}

Font Setup

When you install tc-lib-pdf as a dependency in your project (via composer require or composer install), the fonts from the companion package tc-lib-pdf-font must be generated before they can be used.

Composer does not execute scripts declared by dependencies, so you need to add the font generation step to your consuming project's composer.json file:

{
  "scripts": {
    "tc-lib-pdf-fonts": [
      "[ -d vendor/tecnickcom/tc-lib-pdf-font ] && make -C vendor/tecnickcom/tc-lib-pdf-font deps fonts || true"
    ],
    "post-install-cmd": [
      "@tc-lib-pdf-fonts"
    ],
    "post-update-cmd": [
      "@tc-lib-pdf-fonts"
    ]
  }
}

This ensures fonts are generated automatically when you run:

composer install
composer update
composer require ...

If you prefer to generate fonts manually, run the build in the tc-lib-pdf-font package:

cd vendor/tecnickcom/tc-lib-pdf-font
make deps fonts

Equivalent one-liner from your project root:

make -C vendor/tecnickcom/tc-lib-pdf-font deps fonts

Once fonts are generated, they are cached in vendor/tecnickcom/tc-lib-pdf-font/target/fonts/ and will not be regenerated unless explicitly rebuilt.

You can also add your own fonts and generate their PHP font data with tc-lib-pdf-font. For shared or immutable environments, generate them once into a persistent directory you control (outside vendor/) and point K_PATH_FONTS to that location.

\define('K_PATH_FONTS', '/opt/app/fonts/tc-lib-pdf');

This avoids regenerating fonts on every dependency reinstall and lets multiple deployments reuse the same prepared font set.

Quick Start

The following example assumes the script lives in your project root. If you place it elsewhere, adjust the autoload.php and K_PATH_FONTS paths accordingly.

<?php

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

\define('K_PATH_FONTS', \realpath(__DIR__ . '/vendor/tecnickcom/tc-lib-pdf-font/target/fonts'));

$pdf = new \Com\Tecnick\Pdf\Tcpdf();

$bfont = $pdf->font->insert($pdf->pon, 'helvetica', '', 12);

$page = $pdf->addPage();

$pdf->page->addContent($bfont['out']);

$html = '<h1>Hello, PDF!</h1><p>Generated with tc-lib-pdf.</p>';

$pdf->addHTMLCell($html, 15, 20, 180);

$rawpdf = $pdf->getOutPDFString();

$pdf->renderPDF($rawpdf);

getOutPDFString() returns the raw PDF bytes. renderPDF() streams those bytes to the browser; if you need file storage or an email attachment, keep the returned string and write or hand it off yourself.

For more complete examples — including invoices, images, barcodes, HTML tables, dedicated HTML selector/form/table showcases, PDF/X, and PDF/UA — see the examples directory. Annotation-focused runnable example: examples/E027_annotations.php.

To run the bundled examples locally:

make x       # build example assets
make server  # start a local PHP server

Then open http://localhost:8971/index.php.

If the minimal example fails on first run, verify these two points first:

K_PATH_FONTS resolves to an existing generated font directory.
The companion fonts were generated after composer install or composer update.

PDF Import

tc-lib-pdf can import pages from existing PDFs as Form XObjects and place them on destination pages.

Source registration and page count

$sourceId = $pdf->setImportSourceFile('/path/to/source.pdf');
// or: $sourceId = $pdf->setImportSourceData($rawPdfBytes);

$count = $pdf->getSourcePageCount($sourceId);

Import one page and place it

$tpl = $pdf->importPage($sourceId, 1, [
    'box' => 'CropBox',          // MediaBox|CropBox|BleedBox|TrimBox|ArtBox
    'groupXObject' => true,
    'cache' => true,
    'respectRotation' => true,
]);

$pdf->addPage();
$placed = $pdf->useImportedPage($tpl, 20, 20, 120, 80, [
    'keepAspectRatio' => true,
    'align' => 'CC',             // TL|TC|TR|CL|CC|CR|BL|BC|BR
    'clip' => true,
]);

Append pages from a source document

// Append all pages.
$templates = $pdf->appendDocument($sourceId);

// Append only selected pages.
$templates = $pdf->appendDocument($sourceId, [1, 3, 5]);

// Add one imported page sized to the source page.
$tpl = $pdf->addPageFromImport($sourceId, 2);

Import examples

Single page import: examples/E065_import_single_page.php
Full document append: examples/E066_import_document_append.php
Advanced N-up composition from imported pages: examples/E067_import_page_region_nup.php

Migrating from FPDI-style workflows

If you are migrating legacy FPDI-like code paths, map concepts to the native API as follows:

setSourceFile() -> setImportSourceFile() + getSourcePageCount()
importPage() -> importPage() (returns a typed PageTemplate value object)
useTemplate() -> useImportedPage()
manual page-loop append flows -> appendDocument()

Unlike FPDI numeric template IDs, tc-lib-pdf returns typed PageTemplate objects and keeps import behavior inside the same library stack (tc-lib-*) without external importer dependencies.

Import limitations and fidelity notes

Form and annotation semantics are not merged into editable destination structures; pages are imported as Form XObjects.
Digital signatures in source files are not preserved as valid signatures in the destination output.
Encrypted source PDFs are currently not importable with the bundled parser backend. Password-like options are accepted by the import API, but encrypted inputs fail with an explicit actionable exception.
For multi-stream page contents, import normalizes by decoding and concatenating stream bytes; this can change low-level byte representation while preserving rendered appearance in typical cases.
Transparency-group behavior is conformance-aware: when transparency is disallowed by the active PDF mode (for example PDF/X-1a or PDF/X-3), import suppresses transparency groups to remain compliant.
Setting groupXObject to false can reduce output size, but may change compositing on source pages that rely on transparency blending.

Remote Resources and `fileOptions`

By default tc-lib-pdf does not fetch any remote URLs. Images, fonts, and SVG files referenced by HTTP or HTTPS are blocked unless you explicitly allow the originating hosts. Local file paths are never restricted.

Remote access is controlled by the optional $fileOptions array passed as the last argument to the Tcpdf constructor (and forwarded to initClassObjects()).

Allowing remote hosts

$pdf = new \Com\Tecnick\Pdf\Tcpdf(
    unit: 'mm',
    fileOptions: [
        'allowedHosts' => ['cdn.example.com', 'assets.myapp.io'],
    ],
);

Only the listed host names are permitted. Any attempt to load a resource from an unlisted host is silently blocked. Supply an explicit allowlist rather than a wildcard to limit the attack surface when user-supplied URLs might reach this code path.

All `fileOptions` keys

Key	Type	Default	Description
`allowedHosts`	`string[]`	`[]` (none)	Host names the library may fetch over HTTP/HTTPS. Remote loading is disabled when this list is empty.
`maxRemoteSize`	`int`	`52428800` (50 MiB)	Maximum bytes accepted for a single remote download. Requests exceeding this limit are aborted.
`curlopts`	`array<int, bool\|int\|string>`	`[]`	Per-request cURL options (keyed by `CURLOPT_*` constants) merged on top of the built-in defaults.
`defaultCurlOpts`	`array<int, bool\|int\|string>`	`null`	Replaces the built-in default cURL option set entirely. Omit this key to keep the safe defaults.
`fixedCurlOpts`	`array<int, bool\|int\|string>`	`null`	cURL options that are always enforced and cannot be overridden by `curlopts` — useful for pinning TLS settings in locked-down environments.

Example: pinning TLS and setting a short timeout

$pdf = new \Com\Tecnick\Pdf\Tcpdf(
    unit: 'mm',
    fileOptions: [
        'allowedHosts'  => ['cdn.example.com'],
        'maxRemoteSize' => 10 * 1024 * 1024, // 10 MiB
        'curlopts'      => [
            CURLOPT_TIMEOUT        => 10,
            CURLOPT_CONNECTTIMEOUT => 5,
        ],
        'fixedCurlOpts' => [
            CURLOPT_SSL_VERIFYPEER => true,
            CURLOPT_SSL_VERIFYHOST => 2,
        ],
    ],
);

Digital Signatures

tc-lib-pdf supports detached CMS (PKCS#7) signatures with optional RFC 3161 timestamps and LTV (Long-Term Validation) material, all embedded in a single PDF revision.

Signature-focused runnable examples:

examples/E007_signature_basic.php : basic detached CMS signature with visible signature fields.
examples/E008_signature_timestamp.php : detached CMS signature with RFC 3161 TSA timestamp configuration.
examples/E009_signature_ltv.php : detached CMS signature with LTV validation material embedding.

Basic signature

$pdf->setSignature([
    'signcert'  => 'file:///path/to/cert.pem',
    'privkey'   => 'file:///path/to/key.pem',
    'password'  => '',
    'cert_type' => 2,
    'info'      => [
        'Name'        => 'Jane Smith',
        'Location'    => 'London',
        'Reason'      => 'Document approval',
        'ContactInfo' => 'jane@example.com',
    ],
]);

Adding a TSA timestamp (RFC 3161)

Call setSignTimeStamp() after setSignature() to request a timestamp token from a trusted TSA and embed it in the CMS unsigned attributes:

$pdf->setSignTimeStamp([
    'enabled'        => true,
    'host'           => 'https://freetsa.org/tsr',
    'username'       => '',
    'password'       => '',
    'cert'           => '',
    'hash_algorithm' => 'sha256',   // sha256 | sha384 | sha512
    'policy_oid'     => '',         // optional OID string
    'nonce_enabled'  => true,
    'timeout'        => 30,
    'verify_peer'    => true,
]);

LTV (Long-Term Validation)

Enable LTV via the ltv key inside setSignature(). The library fetches OCSP responses and CRL payloads from the certificate's AIA and CDP extensions and writes them into the same PDF revision as the signature:

$pdf->setSignature([
    'signcert' => 'file:///path/to/cert.pem',
    'privkey'  => 'file:///path/to/key.pem',
    'password' => '',
    'ltv'      => [
        'enabled'     => true,
        'embed_ocsp'  => true,   // fetch OCSP responses
        'embed_crl'   => true,   // fetch CRL payloads (fallback)
        'embed_certs' => true,   // include certificate DER bytes
        'include_dss' => true,   // emit /DSS in catalog
        'include_vri' => true,   // emit /VRI map keyed by cert SHA-1
    ],
]);

When LTV is enabled the output PDF contains /DSS, /VRI, /OCSPs, /CRLs, and /Certs objects, making Adobe-style long-term signature validation feasible without any external retrieval at verification time.

Generating a self-signed test certificate

openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
    -keyout tcpdf.key -out tcpdf.crt
# convert to PKCS#12 if needed
openssl pkcs12 -export -in tcpdf.crt -inkey tcpdf.key -out tcpdf.p12

PDF/X Conformance

tc-lib-pdf supports multiple PDF/X profiles for print-exchange workflows. Pass the mode string as the fifth argument to the Tcpdf constructor:

// Generic PDF/X alias (maps to the library's baseline print-exchange workflow)
$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfx');

// Specific variants
$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfx1a'); // PDF/X-1a:2003
$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfx3');  // PDF/X-3:2003
$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfx4');  // PDF/X-4:2010
$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfx5');  // PDF/X-5g:2010

Each variant automatically applies the appropriate conformance constraints:

Mode	Min PDF version	Transparency	Process colors	GTS_PDFXVersion
`pdfx` / `pdfx3`	1.3	blocked	CMYK forced	PDF/X-3:2003
`pdfx1a`	1.3	blocked	CMYK forced	PDF/X-1a:2003
`pdfx4`	1.6	allowed	unrestricted	PDF/X-4:2010
`pdfx5`	1.6	allowed	unrestricted	PDF/X-5g:2010

All PDF/X modes suppress encryption and JavaScript (not permitted by the ISO 15930 standard).

Runnable examples: examples/E010_pdfx.php through examples/E014_pdfx5.php.

PDF/UA Accessibility

tc-lib-pdf supports tagged PDF output conforming to PDF/UA (ISO 14289). Pass the mode string as the fifth argument to the Tcpdf constructor:

// Generic PDF/UA alias
$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfua');

// Specific parts
$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfua1'); // PDF/UA-1 (PDF 1.7)
$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfua2'); // PDF/UA-2 (PDF 2.0)

When a PDF/UA mode is active the library automatically:

Writes a StructTreeRoot with a ParentTree that maps every page to its tagged content blocks
Emits MarkInfo << /Marked true >> in the document catalog
Sets /Lang (defaults to en-US when not explicitly provided)
Forces ViewerPreferences /DisplayDocTitle true
Maps HTML heading elements (h1–h6) to PDF structure roles H1–H6 with level-clamping to prevent skipped heading levels
Tags text content with MCIDs and wraps each run in the appropriate structure element (P, H1–H6, Link, etc.)
Tags <img> elements as Figure with their alt attribute written as /Alt in the structure element
Emits ActualText entries for ligatures and special glyphs so text extraction and screen readers work correctly

To provide the document language explicitly:

$pdf->setDocInfo(['a_meta_language' => 'de-DE']);

Runnable examples: examples/E015_pdfua.php through examples/E017_pdfua2.php.

Development

# Install all development dependencies
make deps

# List all available Make targets
make help

# Run the full quality pipeline (lint, static analysis, tests, coverage)
make qa

# Generate PDF/X + PDF/UA sample matrix and run external validators (if installed)
make preflight

Build artifacts and reports are written to the target/ directory.

Packaging

The primary distribution channel is Composer. For system-level deployments, RPM and DEB packages are also provided.

make rpm   # build RPM package  → target/RPM/
make deb   # build DEB package  → target/DEB/

When using the RPM or DEB package, bootstrap the library with its system autoloader:

require_once '/usr/share/php/Com/Tecnick/Pdf/autoload.php';

Contributing

Contributions are welcome. Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting a pull request.

Fork the repository and create a feature branch.
Write or update tests for your change.
Run make qa to ensure the full pipeline passes.
Open a pull request with a clear description of the change.

Security vulnerabilities should be reported according to SECURITY.md.

Third-Party Fonts

PHP font metadata files under the fonts directory are covered by the project license (GNU LGPL v3). They can be regenerated with the built-in font utilities.

Original source files are renamed for compatibility and compressed with PHP gzcompress (.z extension) where applicable.

Prefix	Source	License
`freefont`	GNU FreeFont	GNU GPL v3
`pdfa`	tc-font-pdfa (derived from GNU FreeFont)	GNU GPL v3
`dejavu`	DejaVu Fonts 2.35	Bitstream Vera (with DejaVu public-domain changes)
`unifont`	GNU Unifont 15.1.03	GPL v2+ with font embedding exception (also distributed under SIL OFL 1.1)
`cid0`	GNU Unifont (CID mappings)	GPL v2+ with font embedding exception
`core`	Adobe Core14 AFM	Adobe copyright terms (see AFM notices)

ICC Profile

The bundled sRGB.icc profile is sourced from the Debian icc-profiles-free package.

Contact

Nicola Asuni — info@tecnick.com

tecnickcom / tc-lib-pdf

Maintainers

Package info

Fund package maintenance!

Statistics

Security

README

Contents

Overview

Description

For TCPDF Users

Features

Text & Fonts

Layout & Content

Images & Graphics

Security & Standards

PDF Import

Other

Requirements

Installation

Font Setup

Quick Start

PDF Import

Source registration and page count

Import one page and place it

Append pages from a source document

Import examples

Migrating from FPDI-style workflows

Import limitations and fidelity notes

Remote Resources and fileOptions

Allowing remote hosts

All fileOptions keys

Example: pinning TLS and setting a short timeout

Digital Signatures

Basic signature

Adding a TSA timestamp (RFC 3161)

LTV (Long-Term Validation)

Generating a self-signed test certificate

PDF/X Conformance

PDF/UA Accessibility

Development

Packaging

Contributing

Third-Party Fonts

ICC Profile

Contact

Remote Resources and `fileOptions`

All `fileOptions` keys