tc-lib-pdf (TCPDF)

Open Source PHP class for generating PDF documents

tc-lib-pdf is the current generation of TCPDF: a pure-PHP library that writes PDF documents on PHP 8.2 and later, installed through Composer and split across a set of focused packages.

TCPDF started in 2002 and ended up one of the most widely installed PDF engines in PHP. The legacy codebase is now deprecated. New work happens in tc-lib-pdf and the tc-lib packages it builds on.

IMPORTANT: This stack has been installed hundreds of millions of times, and keeping it working across two decades of PDF readers and standards revisions is paid engineering time. If your work depends on it, please consider GitHub Sponsors . The Sponsor page has the tiers and how logo placement works.

Table of contents

Start Here

  • Install:
composer require tecnickcom/tc-lib-pdf

Why tc-lib-pdf

Everything runs in PHP. There is no headless browser to install, no rendering service to call, and nothing to keep alive next to your application. The library pulls together companion packages for fonts, images, graphics, pages, filtering, encryption, and digital signatures behind one document-authoring API.

Given the same inputs it writes the same document, which is what invoicing and archival pipelines need. Option strings are backed by enums throughout, so your IDE and your static analyser both know the accepted values; see /docs/enums/ . And you can install the whole stack or only the tc-lib packages you actually use.

Still evaluating? /comparison/ puts tc-lib-pdf side by side with TCPDF, FPDF, mPDF, Dompdf, and the headless-browser renderers, including the cases where one of those is the better fit.

Which Repository

The legacy TCPDF repository at https://github.com/tecnickcom/TCPDF is deprecated. Development continues at https://github.com/tecnickcom/tc-lib-pdf .

New projects should start on tc-lib-pdf. If legacy TCPDF is already in production, there is no emergency: keep it running and plan the migration in phases.

For TCPDF Users

tc-lib-pdf is not a drop-in replacement for TCPDF:

  • The codebase is split across separate Composer packages instead of a single distribution.
  • The API is strongly typed and organized around companion services such as fonts, pages, graphics, and images.
  • Setup is Composer-first: asset preparation such as font generation is part of project bootstrap, not a bundled step.

The runnable examples in /examples/ cover the equivalent of most TCPDF workflows.

Requirements

  • PHP 8.2 or later
  • Required PHP extensions (enforced by Composer): ctype, filter, hash, json, mbstring, openssl, pcre, xml, zlib
  • Composer

Optional PHP extensions for extended functionality:

  • gd: extended image format handling.
  • curl: required to contact a Timestamp Authority (RFC 3161) when timestamping signatures.
  • intl: Unicode NFC normalization of the PDF file name.
  • bcmath: speeds up the arbitrary precision arithmetic used by the IMB and PDF417 barcode types (a pure-PHP fallback is used when it is missing).

Feature-specific prerequisites:

  • Digital signatures, timestamps, and LTV require signing certificates and keys, plus any TSA or revocation endpoint the configuration references.
  • make preflight runs external validation tools when they are installed.

Installation

For a clean first run:

  1. Install the package with Composer.
  2. Generate the companion font files.
  3. Run the minimal script using the generated K_PATH_FONTS path.
composer require tecnickcom/tc-lib-pdf

Composer writes the constraint for the current stable release into your composer.json.

Font Setup

Font generation is required before the bundled and companion fonts can be used. The detailed workflow is on /docs/fonts/ , including Composer hooks, manual generation, custom font import, and licensing notes.

For the common case, add this hook to your consuming project’s composer.json:

{
    "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"
        ],
        "post-autoload-dump": [
            "@tc-lib-pdf-fonts"
        ]
    }
}

To build fonts manually from the project root:

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

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:   $html,
        posx:   15,
        posy:   20,
        width:  180,
);

$rawpdf = $pdf->getOutPDFString();

$pdf->renderPDF($rawpdf);

getOutPDFString() returns the raw PDF bytes. renderPDF() streams those bytes to the browser; to store them in a file or send them as an attachment, keep the returned string.

realpath() returns false when the fonts directory does not exist. A K_PATH_FONTS error on first run means the fonts have not been generated: see /docs/fonts/ .

For more complete examples, see /examples/ .

What You Can Build

  • Invoices, receipts, and financial statements
  • Shipping labels and barcode-driven logistics documents
  • Compliance and archival PDFs, including PDF/A workflows
  • Branded reports with custom fonts, SVG, and advanced layout controls
  • Interactive documents with forms, annotations, and signatures

Key Capabilities

The highlights are below; /features/ is the full index, area by area, with a link to the guide or runnable example for each entry.

  • Typography and fonts: Unicode 17 data, UAX #9 conformant bidirectional text, Arabic shaping, subsetting, custom fonts, and font tooling. See /docs/fonts/ .
  • Typed option enums across the whole stack, with the string API fully preserved. See /docs/enums/ .
  • HTML, CSS, and SVG rendering: path parsing, markers, text anchoring, and style inheritance, with a depth cap on <use> expansion so cyclic SVG graphs are refused. See /examples/E030_svg/ and /examples/E031_html_features/ .
  • Secure and network-aware integrations: host allowlists and transport controls for remote assets. See /docs/remote-resources/ .
  • Signature workflows: detached CMS signatures, PAdES baseline profiles, RFC 3161 TSA timestamps, and LTV material, each verified before it is embedded, plus two-phase signing for keys held in an HSM, a smart card, or a remote service. See /docs/digital-signatures/ .
  • Standards modes: PDF/A, PDF/X, and PDF/UA conformance, with the problems that cannot be fixed silently reported through getWarnings(). See /docs/standards/ .
  • Hybrid e-invoicing: Factur-X, ZUGFeRD, and Order-X payloads embedded in PDF/A-3 documents by setFacturX(), XMP extension schema included. See /examples/E001_invoice/ .
  • Reproducible output: pin the dates and the file identifier with setDocCreationDate(), setDocModificationDate(), and setFileId() to get the same bytes on every run.
  • PDF reuse: import and place pages from existing PDFs. See /docs/pdf-import/ .
  • Build and packaging workflow: QA, preflight against veraPDF, RPM, and DEB targets. See /docs/development/ .

In-Depth Guides

tc-lib-* Ecosystem

tc-lib-pdf is built on a set of focused, independently versioned packages. Each can be used standalone or as part of the full stack:

  • tc-lib-pdf : Top-level PDF generation library; composes the full package stack.
  • tc-lib-barcode : Generates 1D and 2D barcodes.
  • tc-lib-color : Color conversion and management across RGB, CMYK, HSL, and spot color spaces.
  • tc-lib-file : File and data-URI helpers used internally for asset loading.
  • tc-lib-unicode : Unicode string processing: bidirectional text, normalization, and character utilities.
  • tc-lib-unicode-data : Raw Unicode character data tables used by tc-lib-unicode.
  • tc-lib-pdf-encrypt : PDF encryption and permissions.
  • tc-lib-pdf-filter : PDF stream filters.
  • tc-lib-pdf-font : Font loading, subsetting, and embedding.
  • tc-lib-pdf-graph : Vector graphics primitives.
  • tc-lib-pdf-image : Image loading and embedding.
  • tc-lib-pdf-page : Page geometry, margins, boxes, and page-level attributes.
  • tc-lib-pdf-parser : Reads and parses existing PDF files for import or manipulation.
  • tc-lib-pdf-sign : Digital signature primitives (PKCS#7, CAdES, PAdES baseline) with RFC 3161 timestamps and LTV material.

Contributing

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

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

Security vulnerabilities should be reported according to SECURITY.md .

Contact

Nicola Asuni, info@tecnick.com