安裝

系統需求

需求	版本	用途
PHP	^8.5	唯讀類別、列舉、管道運算子、#[\SensitiveParameter]
ext-openssl	*	AES-256 加密、PKCS#7 簽章、OCSP/TSA 請求
ext-zlib	*	PDF 串流的 Flate 壓縮
ext-mbstring	*	Unicode 字串處理
ext-gd	*	圖片處理（JPEG、PNG、WebP、AVIF）
ext-curl	*	對 OCSP 回應器與 TSA 伺服器發送 HTTP 請求
ext-intl	*	ICU 斷行演算法與地區化格式處理

驗證所有擴充套件是否已安裝：

php -r "foreach(['openssl','zlib','mbstring','gd','curl','intl'] as \$e){echo \$e.': '.(extension_loaded(\$e)?'OK':'MISSING').PHP_EOL;}"

快速安裝

僅 Core

composer require yeeefang/tcpdf-next

+ Laravel

composer require yeeefang/tcpdf-next yeeefang/tcpdf-next-laravel

+ Symfony

composer require yeeefang/tcpdf-next yeeefang/tcpdf-next-symfony

+ Artisan

composer require yeeefang/tcpdf-next yeeefang/tcpdf-next-artisan

完整安裝

composer require yeeefang/tcpdf-next yeeefang/tcpdf-next-pro yeeefang/tcpdf-next-artisan yeeefang/tcpdf-next-laravel

Core 套件

composer require yeeefang/tcpdf-next

相依套件： phpseclib/phpseclib ^3.0（RSASSA-PSS、ASN.1、X.509）

功能性擴充

Artisan 套件（Chrome CDP）

composer require yeeefang/tcpdf-next-artisan

額外需求：

• chrome-php/chrome ^1.15
• 系統需安裝 Chrome 或 Chromium 瀏覽器

# Ubuntu/Debian
apt-get install chromium-browser

# macOS
brew install --cask chromium

# 或透過環境變數指定路徑
export CHROME_PATH=/usr/bin/google-chrome

Pro 套件（商業版）

composer require yeeefang/tcpdf-next-pro

授權方式： 每個應用程式 $1,000 USD，依主版本永久授權。

額外相依套件： phpseclib/phpseclib ^3.0 | 選用：ext-pkcs11

設定你的授權金鑰：

# .env
TCPDF_PRO_LICENSE_KEY=your-license-key

框架整合

Laravel 套件

composer require yeeefang/tcpdf-next-laravel

需求： Laravel ^12.0

ServiceProvider 會自動註冊。發佈設定檔：

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

Symfony 套件

composer require yeeefang/tcpdf-next-symfony

需求： Symfony ^7.0

Bundle 會透過 Symfony Flex 自動設定。若需手動註冊：

// config/bundles.php
return [
    // ...
    Yeeefang\TcpdfNext\Symfony\TcpdfNextBundle::class => ['all' => true],
];

CodeIgniter 套件

composer require yeeefang/tcpdf-next-codeigniter

需求： CodeIgniter ^4.0

在 app/Config/Services.php 中註冊服務，或使用自動偵測。

相容性

Adaptation 套件（TCPDF 遷移）

composer require yeeefang/tcpdf-next-adaptation

TCPDF 6.2.13 的無痛替換轉接器 — 將 252 個舊版方法映射到 TCPDF-Next 的現代 API。支援 Header() / Footer() 覆寫（透過非 final 類別），以及舊版輔助類別（TCPDF_STATIC、TCPDF_FONTS、TCPDF_COLORS、TCPDF_IMAGES）。

Docker 設定

🐳 Docker for Legacy PHP Environments

如果你的正式環境 PHP 版本低於 8.5，可以使用 Docker 隔離 TCPDF-Next。

FROM php:8.5-cli

RUN apt-get update && apt-get install -y \
    libicu-dev libpng-dev libjpeg-dev libwebp-dev libzip-dev \
    && docker-php-ext-configure gd --with-jpeg --with-webp \
    && docker-php-ext-install gd intl zip

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

COPY . /app
WORKDIR /app
RUN composer install --no-dev --optimize-autoloader

若需使用 Chrome（Artisan 套件）：

FROM php:8.5-cli

RUN apt-get update && apt-get install -y \
    libicu-dev libpng-dev libjpeg-dev libwebp-dev chromium \
    && docker-php-ext-configure gd --with-jpeg --with-webp \
    && docker-php-ext-install gd intl

ENV CHROME_PATH=/usr/bin/chromium

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
COPY . /app
WORKDIR /app
RUN composer install --no-dev --optimize-autoloader

驗證安裝

<?php
require 'vendor/autoload.php';

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::createStandalone()->addPage()->setFont('Helvetica', '', 12)->cell(0, 10, 'OK');
echo "TCPDF-Next is working. Classes loaded: " . count(get_declared_classes()) . "\n";