# TCPDF in 7.x: a compatibility facade over tc-lib-pdf, and when to stop using it

> TCPDF is deprecated and in maintenance-only mode. Version 7 keeps the legacy API but delegates rendering to tc-lib-pdf, moves font assets into Composer packages, and changes where you have to look when a page fails to render.

**tecnickcom/TCPDF** — Deprecated: PHP PDF library, superseded by tc-lib-pdf (https://github.com/tecnickcom/tc-lib-pdf)

- Repository: https://github.com/tecnickcom/TCPDF
- Website: https://tcpdf.org
- Stars: 4,528 · Forks: 1,578
- Language: PHP
- License: NOASSERTION
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/tecnickcom-tcpdf

## What TCPDF 7.x is actually for

TCPDF generates PDF documents and barcodes from PHP code, with no external binary or headless browser in the loop. Text rendering, page composition, graphics, signatures, forms and standards-oriented output are all handled by the library itself. The README describes the package as `tecnickcom/tcpdf` and lists its author as Nicola Asuni.

The audience that matters now is narrow. The README states plainly that TCPDF is deprecated and in maintenance-only mode, and that active development has moved to tc-lib-pdf. It is still installed 100M+ times across 500+ PHP packages according to the README, which is the real reason this repository still gets releases: shared infrastructure that other packages sit on. If you are choosing a PDF library for a greenfield PHP service, TCPDF is the wrong starting point. If you maintain an application that calls `new TCPDF(...)` today, 7.x is aimed at you.

## The facade architecture: legacy API, tc-lib-pdf engine

Starting with version 7, the `TCPDF` class no longer contains its own PDF engine. It is a compatibility facade. Every public method is a thin wrapper that delegates to `\Com\Tecnick\Pdf\Tcpdf` from the `tecnickcom/tc-lib-pdf` engine, while a small internal state layer reproduces the legacy stateful cursor and page model: current X/Y, margins, fonts, colors, automatic page breaks, headers and footers.

The README says all 291 public method signatures are identical to legacy TCPDF, so existing calls to `AddPage()`, `SetFont()`, `Cell()`, `writeHTML()` and `Output()` keep working. One method is new: `getPDFFilename()`, which returns the file name `Output()` used, after the engine sanitizes it. Per-method delegation status is documented in MAPPING.md with the labels `delegated`, `adapter`, `shim`, `intentional-noop` and `blocked`, and the README says that table is machine-verified against the class. That file is the first place to look when a method behaves differently than you remember.

The important consequence is that output is structurally equivalent, not byte-identical. Page sizes and content match, but the modern engine's line-breaking and font metrics can differ slightly, so a long flowing document may paginate one page earlier or later. If you have snapshot tests that hash generated PDFs, this upgrade will break them for reasons that are not bugs.

## Installing TCPDF with Composer and rendering a first page

The package installs through Composer as `tecnickcom/tcpdf`. Font assets are the part that catches people out: they are generated at install time and are not shipped in the package, and Composer only runs scripts declared by the root project. A project that requires TCPDF as a dependency therefore has to run the font generation itself.

Add this to your own `composer.json` so the step runs after install, update and autoload dump:

```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"]
  }
}
```

If you would rather generate the fonts once by hand, run the build from the project root instead:

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

The sentinel that tells you the assets exist is `vendor/tecnickcom/tc-lib-pdf-font/target/fonts/core/helvetica.json`. The README warns that a missing asset directory shows up as `unable to read file: helvetica.json` on the first page, which is a font problem, not a page-content problem. In a checkout of this repository, the Makefile provides `make deps` to install Composer dependencies and initialize tc-lib font assets, `make fonts` to initialize fonts only when missing, and `make fonts-rebuild` to force a full rebuild.

For a first render, the repository ships `examples/example_001.php` through `examples/example_023.php`. The Makefile defines a default example server port of `8971` via `PORT?=8971`. The README does not document a single canonical run command for those examples, so read the file you pick before running it.

## Font handling is the biggest operational change

Repository-shipped `fonts/` assets are removed. TCPDF now resolves bundled fonts from tc-lib assets discovered under `vendor/tecnickcom/tc-lib-pdf-font/target/fonts/`, and font assets are provided by the `tecnickcom/tc-lib-pdf-font` package.

The affected deployments are specific. Anyone who relied on local `fonts/` files without Composer dependencies is hit. So is any application with custom `K_PATH_FONTS` assumptions tied to a repository-relative fonts folder, and any integration that uses custom or generated font definitions and expects PHP-only descriptor files. The README's migration steps are to install dependencies with Composer, make sure the tc-lib font assets are present, keep calling `SetFont()` and `AddFont()` but validate that each custom family resolves from tc-lib assets or from an explicit font path, and update deployment packaging so `vendor/` font assets are shipped in production.

That last point is the one teams miss. If your build step strips `vendor/tecnickcom/tc-lib-pdf-font/target/fonts/`, or your container image copies only application code, PDF generation will fail at runtime on the first page with the helvetica.json error. Font assets are now build artifacts, and build artifacts need to survive the deploy.

## Breaking changes and behaviours that are not reproduced

The README states that some legacy behaviours are intentionally not reproduced, and lists legacy font definitions, EPS/AI vector import, always-on stream compression, policy-based local file access, and assorted no-ops among the features dropped or changed where the modern engine's model takes precedence. It points to the Breaking Changes section and to the per-method notes in MAPPING.md for the full list.

This is where TCPDF 7.x can be the wrong tool. If your pipeline imports EPS or AI vector files, or depends on stream compression always being on, or relies on policy-based local file access rules, the facade does not promise those semantics. A method marked `intentional-noop` or `blocked` in MAPPING.md will not error loudly; it will simply not do what the legacy code did. Anyone upgrading a document pipeline that touches those areas should read MAPPING.md method by method before touching production.

The pagination drift is a second, quieter failure mode. Because output is structurally equivalent rather than byte-identical, a document that previously fit on three pages may now run to four. For invoices, statements or any output with a fixed page count assumption downstream, that is a real change even though the content is the same.

## tc-lib-pdf versus staying on TCPDF

The alternative the project itself names is `tecnickcom/tc-lib-pdf`, the modern, modular successor. The difference in approach is architectural rather than cosmetic. TCPDF 7.x is a facade: one large class preserving 291 legacy method signatures, with a stateful cursor and page model layered on top of the new engine for backwards compatibility. tc-lib-pdf is the engine itself, described in the README as Composer-first with stronger type-safety, and it is where active feature development happens.

Choosing between them is a question of what you are protecting. Staying on TCPDF preserves existing call sites and buys time; the cost is a compatibility layer that carries legacy state and a set of documented behaviours that are deliberately not reproduced. Moving to tc-lib-pdf means rewriting call sites against a modular API, but you stop paying for the facade. The README's own migration path is phased: new projects install tc-lib-pdf, existing TCPDF users keep it for current production workloads and migrate in phases, and teams that want modern architecture and type-safety should prioritize tc-lib-pdf. Note that FPDF, which appears in some search queries, is a separate library and is not part of this project's migration story.

## Upgrade cost, licence and who should stay

The README lists the licence as GNU LGPL v3, with the full text in LICENSE.TXT, and the repository's LICENSE.TXT is the authoritative file. LGPL matters for distribution: if you ship a modified copy of the library, the licence terms attach to that copy. That is a general property of the licence, not advice about your situation; read LICENSE.TXT and, if the distinction affects your product, get proper counsel.

Upgrade cost concentrates in three places: font assets becoming Composer-generated build artifacts, `vendor/` needing to ship to production, and pagination or method behaviour drifting from the legacy engine. The repository is not archived and the last push was on 2026-09-21, with 7.0.11 released the same day, 7.0.10 on 2026-09-14 and 7.0.9 on 2026-09-07. Releases are still landing, but the README frames them as maintenance for legacy systems and critical compatibility fixes rather than feature work, and it points maintainers of dependent products at the sponsorship link for continued maintenance.

Who should stay: applications pinned to the legacy API that need the facade to keep working while they plan a phased move. Who should not start here: new PHP projects, and anyone whose pipeline depends on EPS/AI import, always-on stream compression or policy-based local file access. Verify first that `make -C vendor/tecnickcom/tc-lib-pdf-font deps fonts` produces `vendor/tecnickcom/tc-lib-pdf-font/target/fonts/core/helvetica.json` in your build, that MAPPING.md marks every method you call as `delegated` or `adapter` rather than `blocked`, and that your deployment actually ships the `vendor/` font tree.

## Conclusion

Adopt TCPDF only if you already have it in production and need the 7.x facade to keep working; new PHP projects should start with tecnickcom/tc-lib-pdf instead. Before upgrading, verify that Composer can generate the tc-lib font assets, that vendor/ is shipped in your deployment artifact, and that no integration depends on the removed repository fonts/ directory or on byte-identical pagination.

## FAQ

### What is TCPDF?

TCPDF is a pure-PHP library for generating PDF documents and barcodes directly in application code, covering text rendering, page composition, graphics, signatures, forms and standards-oriented output. The README states it is deprecated and in maintenance-only mode, with active development moved to tc-lib-pdf.

### How do I install TCPDF with Composer?

Install the `tecnickcom/tcpdf` package with Composer, then add the tc-lib-pdf-fonts script to your own composer.json so font assets are generated after install, update and autoload dump. Font assets are not shipped in the package, and Composer only runs scripts declared by the root project.

### How do I use TCPDF in PHP?

Existing integrations keep calling `new TCPDF(...)`, `AddPage()`, `SetFont()`, `Cell()`, `writeHTML()` and `Output()` exactly as before, because all 291 public method signatures are unchanged. The repository ships examples in `examples/example_001.php` through `examples/example_023.php`.

### What is a TCPDF error like "unable to read file: helvetica.json"?

The README states that a missing asset directory is reported as `unable to read file: helvetica.json` on the first page. The fix is generating the tc-lib font assets so that `vendor/tecnickcom/tc-lib-pdf-font/target/fonts/core/helvetica.json` exists, and shipping the `vendor/` font tree to production.

### How do I install TCPDF in PHP?

Install the `tecnickcom/tcpdf` package through Composer and make sure the tc-lib font assets are generated, since repository-shipped `fonts/` assets are removed in version 7. In a checkout of this repository the Makefile targets `make deps` and `make fonts` handle dependency and font setup.

## Sources

- [Issues](https://github.com/tecnickcom/TCPDF/issues)
- [Project website](https://tcpdf.org)
- [README](https://github.com/tecnickcom/TCPDF/blob/main/README.md)
- [Releases](https://github.com/tecnickcom/TCPDF/releases)
- [tecnickcom/TCPDF on GitHub](https://github.com/tecnickcom/TCPDF)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tecnickcom-tcpdf