README

Enterprise-grade PDF 2.0 generation for PHP 8.5+

A modern, high-performance PDF library built from the ground up on ISO 32000-2:2020 (PDF 2.0) with full PAdES B-LTA digital signature support, PDF/A-4 archival compliance, and seamless Laravel 12 integration.

企業級 PDF 2.0 產生器 — PHP 8.5+

基於 ISO 32000-2:2020 (PDF 2.0) 全新打造的現代化高效能 PDF 函式庫，完整支援 PAdES B-LTA 數位簽章、PDF/A-4 長期保存標準，以及 Laravel 12 無縫整合。

Features / 功能特色

PDF 2.0 Core / PDF 2.0 核心

• ISO 32000-2:2020 compliant — Pure PDF 2.0 output with cross-reference streams, no legacy compatibility overhead
• Cross-reference streams — Binary compressed xref for smaller file sizes
• AES-256 encryption (AESV3) — Revision 6 security handler, the only encryption method permitted in PDF 2.0
• UTF-8 native — Full Unicode support with UTF-16BE string encoding

符合 ISO 32000-2:2020 — 純 PDF 2.0 輸出，使用交叉引用串流、AES-256 加密、原生 UTF-8 支援

Digital Signatures / 數位簽章

• PAdES B-B — Basic electronic signature with ETSI.CAdES.detached
• PAdES B-T — Signature with trusted timestamp (RFC 3161 TSA)
• PAdES B-LT — Long-term validation with embedded DSS (certificates, OCSP, CRL)
• PAdES B-LTA — Long-term archival with document timestamps (indefinite validity)
• PKCS#7/CMS — Standards-compliant CMS SignedData construction
• Archival Loop — Periodic re-timestamping to maintain validity beyond TSA certificate expiration

完整 PAdES B-LTA 簽章鏈 — 從基礎簽章到長期保存，支援 TSA 時間戳、DSS 文件安全儲存、OCSP 即時驗證、CRL 撤銷清單，實現永久可驗證的數位簽章。

LTV (Long-Term Validation) / 長期驗證

• Document Security Store (DSS) — Embedded validation material per ISO 32000-2 §12.8.4.3
• Validation Related Information (VRI) — Per-signature validation data
• OCSP Client — Real-time certificate status checking (RFC 6960)
• CRL Fetcher — Certificate revocation list download with caching
• Automatic chain walking — Collects validation material for the entire certificate chain

自動化 LTV 長期驗證 — DSS 文件安全儲存、VRI 驗證資訊、OCSP 即時憑證狀態查詢、CRL 撤銷清單，自動蒐集完整憑證鏈驗證材料。

PDF/A-4 Archival / PDF/A-4 長期保存

• ISO 19005-4:2020 — Full PDF/A-4 compliance based on PDF 2.0
• XMP Metadata — Automatic generation with pdfaid identification schema
• ICC Color Profiles — Bundled sRGB profile with output intent
• Font enforcement — All fonts must be embedded (no standard 14)
• Validation — Runtime checks for encryption prohibition, color space compliance

完整 PDF/A-4 合規 — 基於 PDF 2.0 的最新長期保存標準，XMP 元資料自動產生、ICC 色彩設定檔、強制字型嵌入。

Laravel 12 Integration / Laravel 12 整合

• Service Provider with auto-discovery — zero configuration
• Facade (Pdf::) for expressive syntax
• Queued generation — Async PDF creation via Laravel queues for high throughput
• Octane compatible — Stateless design, no shared mutable state
• HTTP responses — Inline display and download helpers

Laravel 12 深度整合 — ServiceProvider 自動發現、Facade 語法、Queue 非同步產生、Octane 相容、HTTP 回應輔助。

PHP 8.5 Features / PHP 8.5 新功能

• Pipe operator (|>) — Clean data transformation chains
• Clone with — Immutable value objects (PageSize, Dimension, Position)
• #[\NoDiscard] — API safety for critical return values
• Asymmetric visibility — Controlled property access
• Readonly classes — Immutable DTOs throughout
• Enums — Type-safe configurations (Orientation, Alignment, SignatureLevel)

充分運用 PHP 8.5 — Pipe Operator、Clone With、NoDiscard 屬性、不可變值物件、列舉型別。

Requirements / 系統需求

• PHP >= 8.5
• Extensions: openssl, zlib, mbstring, gd, curl
• Laravel >= 12.0 (optional, for framework integration)

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 Generation / 基本 PDF 產生

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setTitle('My Document')
    ->setAuthor('Yeeefang')
    ->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');

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',
    extraCertPaths: ['/path/to/intermediate-ca.pem'],
);

$tsa = new TsaClient(
    tsaUrl: 'https://freetsa.org/tsr',
);

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

PDF/A-4 Archival Document / PDF/A-4 保存文件

use Yeeefang\TcpdfNext\Archive\PdfAVersion;
use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setTitle('Archival Document')
    ->enablePdfA(PdfAVersion::PdfA4)
    ->addPage()
    ->setFont('DejaVuSans', '', 12)
    ->cell(0, 10, 'This document conforms to PDF/A-4.')
    ->save('/path/to/archive.pdf');

Laravel Usage / Laravel 使用方式

// In a controller
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");
    }
}

Queued Generation / 佇列產生

use Yeeefang\TcpdfNext\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    outputPath: storage_path("invoices/invoice-{$id}.pdf"),
    builder: fn($doc) => $doc
        ->setTitle('Invoice')
        ->addPage()
        ->setFont('DejaVuSans', '', 12)
        ->cell(0, 10, 'Generated asynchronously'),
);

Architecture / 架構

src/
├── Archive/          # PDF/A-4 compliance (XMP, ICC, OutputIntent)
│                     # PDF/A-4 合規（XMP 元資料、ICC 色彩、輸出意圖）
├── Contracts/        # Interfaces & Enums
│                     # 介面與列舉
├── Core/             # Document, ObjectRegistry, CrossReferenceStream
│                     # 文件核心、物件登錄、交叉引用串流
├── Laravel/          # ServiceProvider, Facade, Jobs, HTTP
│                     # Laravel 整合層
├── Security/
│   ├── Encryption/   # AES-256 (AESV3) per PDF 2.0
│   │                 # AES-256 加密（PDF 2.0 唯一允許）
│   ├── Ltv/          # DSS, VRI, OCSP, CRL
│   │                 # 長期驗證（文件安全儲存、驗證資訊、OCSP、CRL）
│   ├── Signature/    # PAdES orchestrator, CMS builder, ByteRange
│   │                 # PAdES 簽章協調器、CMS 建構、ByteRange 計算
│   └── Timestamp/    # RFC 3161 TSA client, Document timestamps
│                     # RFC 3161 時間戳客戶端、文件時間戳
├── Support/          # BinaryBuffer for high-performance PDF stream I/O
│                     # 高效能二進位緩衝區
├── Typography/       # Font parsing, subsetting, management
│                     # 字型解析、子集化、管理
├── ValueObjects/     # Immutable types (Dimension, Position, PageSize, Margin)
│                     # 不可變值物件
└── Writer/           # PDF 2.0 serializer with xref streams
                      # PDF 2.0 序列化器

Standards Compliance / 標準合規

Configuration / 設定

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

Key environment variables / 關鍵環境變數:

TCPDF_PAGE_FORMAT=A4
TCPDF_PDFA=4                          # Enable PDF/A-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
TCPDF_QUEUE_NAME=pdf

Performance / 效能

TCPDF-Next is designed for high-throughput scenarios:

• Stateless architecture — Safe for Laravel Octane (Swoole/RoadRunner)
• Stream compression — FlateDecode on all content and xref streams
• Font subsetting — Only embed glyphs actually used
• Async queue support — Offload generation to background workers
• PHP 8.5 optimized — Benefits from pack(), str_pad(), implode() performance improvements

TCPDF-Next 針對高吞吐量場景設計 — 無狀態架構（Octane 安全）、串流壓縮、字型子集化、非同步佇列、PHP 8.5 效能優化。

Roadmap / 路線圖

• Complete HTML/CSS to PDF renderer / 完整 HTML/CSS 轉 PDF 渲染器
• Table layout engine / 表格排版引擎
• Barcode generation (QR, Code128, EAN) / 條碼產生
• SVG/EPS vector image support / SVG/EPS 向量圖支援
• Header/Footer templates / 頁首頁尾模板
• Full font subsetting (glyph remapping) / 完整字型子集化
• phpseclib integration for proper ASN.1 manipulation / phpseclib 整合

License / 授權

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

Credits / 致謝

Built upon the legacy of TCPDF by Nicola Asuni, reimagined for the modern PHP ecosystem.

基於 Nicola Asuni 的 TCPDF 遺產，為現代 PHP 生態系統重新設計打造。