README

A modern rewrite of TCPDF for PHP 8.5+

Based on the classic TCPDF, rebuilt from scratch to adopt current standards (ISO 32000-2:2020 / PDF 2.0) while dropping legacy compatibility. If you know TCPDF, you'll feel right at home — same concepts, cleaner API, modern PHP.

TCPDF 的現代化改寫版 — PHP 8.5+

以經典 TCPDF 為基礎，從頭重寫以採用現行標準（ISO 32000-2:2020 / PDF 2.0），捨棄舊版相容性包袱。熟悉 TCPDF 的開發者可以無痛上手——相同概念，更乾淨的 API，現代化 PHP。

What Changed from TCPDF / 跟原版 TCPDF 的差異

	TCPDF (Original)	TCPDF-Next
PHP	7.1+	8.5+ (enums, readonly, pipe operator)
Architecture	Single 25K-line class	~80 focused classes
PDF Version	1.x ~ 2.0 mixed	Pure PDF 2.0 only
Cross-Ref	Traditional xref table	xref streams (compressed)
Encryption	RC4 ~ AES-256	AES-256 AESV3 only (PDF 2.0)
Signatures	Basic PKCS#7	PAdES B-B / B-T / B-LT / B-LTA
PDF/A	PDF/A-1b	PDF/A-4 (ISO 19005-4:2020)
LTV	None	Full (DSS, VRI, OCSP, CRL)
API Style	Procedural	Fluent method chaining
Laravel	None	Full integration (Facade, Queue, Octane)

Features / 功能

PDF Generation / PDF 產生

Text output: cell(), multiCell(), text(), write()
HTML/CSS rendering: writeHtml() with full tag support (<table>, <div>, <h1>-<h6>, <ul>/<ol>, <a>, <img>, etc.)
Table engine with colspan/rowspan, auto column width, header styling
Image embedding (JPEG, PNG) with positioning and scaling
Multi-column layout
Automatic page breaks

Graphics / 圖形

Shapes: line, rect, roundedRect, circle, ellipse, polygon, regularPolygon, starPolygon, arrow
Bezier curves and polycurves
Pie sectors (for charts)
Colors: RGB, CMYK, Grayscale, Spot colors
Transparency and blend modes
Linear/radial gradients
Line styles: solid, dashed, dotted, custom patterns
Crop marks, registration marks, color bars

Geometric Transformations / 幾何變換

Rotate, Scale, Translate, Skew
Mirror (horizontal, vertical, point, line)
Full CTM matrix support

Text Features / 文字功能

TrueType/OpenType font embedding with subsetting
Full Unicode support (UTF-8)
Text rendering modes (fill, stroke, clip, invisible)
Text shadows
Character spacing and font stretching
RTL text support (Arabic, Hebrew)
Automatic hyphenation

Headers & Footers / 頁首頁尾

Configurable header with title, description, logo
Automatic page numbering in footer
Custom callbacks for full control
Separator lines

Navigation / 導航

Bookmarks (hierarchical outlines)
Table of contents (auto-generated with dot leaders)
Internal links and named destinations
External URL links
Text annotations

Barcodes / 條碼

1D: CODE 39, CODE 93, CODE 128, EAN-8/13, UPC-A/E, I25, S25, CODABAR, CODE 11, MSI, POSTNET, PLANET, IMB, Pharmacode
2D: QR Code, DataMatrix, PDF417

Forms / 表單

Text fields, checkboxes, radio buttons
List boxes, combo boxes, buttons
JavaScript actions

Security / 安全

AES-256 encryption (AESV3, Revision 6) with SASLprep password normalization (RFC 4013)
PAdES B-B through B-LTA digital signatures (ETSI EN 319 142-1)
RSASSA-PSS signature algorithm support (ETSI TS 119 312)
RFC 3161 TSA timestamps with nonce and mTLS
LTV: DSS, VRI (optional, ETSI-compliant default), OCSP, CRL, archival loop
Document timestamps for indefinite validity
SSRF protection on all external URL access

PDF/A-4 / 長期保存

ISO 19005-4:2020 compliance
XMP metadata with pdfaid namespace
ICC color profiles with output intent
Font embedding enforcement
Runtime validation

Advanced / 進階功能

SVG image support
EPS/PostScript support
Optional Content Layers (OCG)
Form XObject templates
Transaction/rollback
Booklet mode (saddle-stitch reordering)
File attachments
Embedded JavaScript
Page operations (move, copy, delete)
Page regions (no-write zones)
Viewer preferences and display modes

Laravel 12 Integration / Laravel 12 整合

Service Provider with auto-discovery
Pdf:: Facade
Queue-based async generation
Octane compatible (stateless)
HTTP response helpers (inline/download)

Accessibility / 無障礙

PDF/UA tagged structure support
Role mapping (RoleMap)
Structure elements for semantic document markup

PHP 8.5 Features / PHP 8.5 特性

Pipe operator (|>)
Clone with
#[\NoDiscard]
Asymmetric visibility
Readonly classes
Enums

Testing / 測試

PHPUnit 12 with 171 tests and 365 assertions covering:

Module	Tests	Description
ValueObjects	24	PageSize, Dimension, Margin, Position, Unit
Core	28	ObjectRegistry, BinaryBuffer, CrossReferenceStream, TransactionManager
Contracts	8	Orientation, Alignment, OutputDestination, Interfaces
Typography	8	FontType, FontInfo
Graphics	6	ColorSpace
Security	25	SignatureLevel, ByteRangeCalculator, SignatureAlgorithm, SaslPrep, DssBuilder
Archive	15	PdfAVersion, XmpMetadata
Barcode	8	BarcodeType, Barcode2DType
Form	10	FormFieldType
Integration	7	PDF skeleton, cross-module, extensions, directory structure

# Run all tests
composer test

# Run only unit tests
composer test:unit

# Run only integration tests
composer test:integration

# Generate coverage report
composer test:coverage

# Static analysis (PHPStan level 8)
composer analyse

Requirements / 系統需求

PHP >= 8.5
Extensions: openssl, zlib, mbstring, gd, curl, intl
Laravel >= 12.0 (optional)
phpseclib/phpseclib ^3.0 (for RSASSA-PSS signatures)

Installation / 安裝

composer require yeeefang/tcpdf-next

Laravel Setup / Laravel 設定

The service provider is auto-discovered. To publish the configuration:

php artisan vendor:publish --tag=tcpdf-next-config

Quick Start / 快速開始

Basic PDF / 基本 PDF

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setTitle('My Document')
    ->addPage()
    ->setFont('DejaVuSans', '', 12)
    ->cell(0, 10, 'Hello, PDF 2.0!', newLine: true)
    ->cell(0, 10, '你好，PDF 2.0！', newLine: true)
    ->save('/path/to/output.pdf');

HTML Table / HTML 表格

$pdf = Document::create()
    ->addPage()
    ->setFont('DejaVuSans', '', 10)
    ->writeHtml('
        <h2>Invoice Items</h2>
        <table>
            <tr><th>Item</th><th>Qty</th><th>Price</th></tr>
            <tr><td>Widget</td><td>10</td><td>$5.00</td></tr>
            <tr><td>Gadget</td><td>3</td><td>$12.00</td></tr>
        </table>
    ')
    ->save('/path/to/invoice.pdf');

Drawing / 圖形繪製

$pdf = Document::create()
    ->addPage()
    ->setDrawColor(255, 0, 0)
    ->setFillColor(200, 220, 255)
    ->rect(50, 700, 200, 100, 'B')
    ->circle(300, 600, 40, 'S')
    ->arrow(100, 500, 300, 500)
    ->roundedRect(50, 400, 200, 80, 10, 'B')
    ->save('/path/to/graphics.pdf');

Digital Signature (PAdES B-LTA) / 數位簽章

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Security\Signature\{CertificateInfo, SignatureLevel};
use Yeeefang\TcpdfNext\Security\Timestamp\TsaClient;

$cert = CertificateInfo::fromFiles(
    certPath: '/path/to/certificate.pem',
    keyPath: '/path/to/private-key.pem',
    password: 'key-password',
);

$pdf = Document::create()
    ->setTitle('Signed Document')
    ->setSignature($cert, SignatureLevel::PAdES_B_LTA, new TsaClient('https://freetsa.org/tsr'))
    ->addPage()
    ->setFont('DejaVuSans', '', 12)
    ->cell(0, 10, 'This document is digitally signed with LTV.')
    ->save('/path/to/signed.pdf');

Laravel Usage / Laravel 使用

use Yeeefang\TcpdfNext\Laravel\Facades\Pdf;
use Yeeefang\TcpdfNext\Laravel\Http\PdfResponse;

class InvoiceController extends Controller
{
    public function show(Invoice $invoice)
    {
        $pdf = Pdf::create()
            ->setTitle("Invoice #{$invoice->number}")
            ->addPage()
            ->setFont('DejaVuSans', '', 12)
            ->cell(0, 10, "Invoice #{$invoice->number}");

        return PdfResponse::inline($pdf, "invoice-{$invoice->number}.pdf");
    }
}

Architecture / 架構

src/
├── Archive/          # PDF/A-4 (XMP, ICC, OutputIntent)
├── Barcode/          # 1D & 2D barcode generators
├── Content/          # Text rendering, shadows, JS
├── Contracts/        # Interfaces & enums
├── Core/             # Document, ObjectRegistry, CrossReferenceStream
├── Form/             # Interactive form fields
├── Graphics/         # Drawing engine, colors, transforms, layers, SVG/EPS
├── Html/             # HTML/CSS parser, table engine
├── Laravel/          # ServiceProvider, Facade, Jobs, HTTP
├── Layout/           # Headers/footers, columns, pages, booklet
├── Navigation/       # Bookmarks, links, TOC, annotations, attachments
├── Security/
│   ├── Encryption/   # AES-256 (AESV3)
│   ├── Ltv/          # DSS, VRI, OCSP, CRL
│   ├── Signature/    # PAdES, CMS, ByteRange
│   └── Timestamp/    # RFC 3161 TSA
├── Support/          # BinaryBuffer
├── Typography/       # Font parsing, subsetting
├── ValueObjects/     # Dimension, Position, PageSize, Margin
└── Writer/           # PDF 2.0 serializer, viewer preferences

Standards / 標準

Standard	Description	Status
ISO 32000-2:2020	PDF 2.0	Implemented
ISO 19005-4:2020	PDF/A-4	Implemented
ETSI EN 319 142-1	PAdES Baseline Signatures	B-B through B-LTA
RFC 3161	Time-Stamp Protocol	Implemented
RFC 5652	Cryptographic Message Syntax	PKCS#7/CMS
RFC 6960	OCSP	Implemented

Configuration / 設定

See config/tcpdf-next.php for all available options.

TCPDF_PAGE_FORMAT=A4
TCPDF_PDFA=4
TCPDF_SIGN_ENABLED=true
TCPDF_SIGN_CERT=/path/to/cert.pem
TCPDF_SIGN_KEY=/path/to/key.pem
TCPDF_SIGN_LEVEL=B-LTA
TCPDF_TSA_URL=https://freetsa.org/tsr

Security / 安全通報

If you discover a security vulnerability, please follow the responsible disclosure process. Do NOT open a public issue.

如果您發現安全漏洞，請遵循安全通報流程。請勿建立公開 issue。

Contributing / 貢獻

Contributions are welcome! Please read the contributing guide before submitting a pull request.

歡迎貢獻！提交 PR 前請先閱讀貢獻指南。

Changelog / 變更紀錄

See CHANGELOG.md for all notable changes.

詳見 CHANGELOG.md 了解所有重要變更。

License / 授權

LGPL-3.0-or-later — See LICENSE for details.

Credits / 致謝

Rewritten from TCPDF by Nicola Asuni, modernized for PHP 8.5 and current PDF/signature standards.

基於 Nicola Asuni 的 TCPDF 改寫，針對 PHP 8.5 與現行 PDF/簽章標準進行現代化。

Special thanks to Edison — your silence gave me the time to fight this massive project, even if I was Emo the whole time.

特別感謝小浩 — 不理我，才能一邊Emo一邊跟這個龐大的專案決鬥。

yeeefang / tcpdf-next

Maintainers

Details