為什麼選擇 PHP 8.5+？

TCPDF-Next 在設計上就要求 PHP 8.5+。這不是隨意的限制——函式庫中使用的每一項現代 PHP 特性，都直接提升了程式碼品質、安全性與開發者體驗。

我們使用的 PHP 8.5 特性

特性	對 TCPDF-Next 的效益
Readonly classes	不可變的值物件（PageSize、Margin、Color、FontInfo）— 杜絕意外修改的錯誤
Backed enums	型別安全的設定（Orientation::Portrait、BarcodeType::QRCode、SignatureLevel::PAdES_B_LTA）
Named arguments	自我描述的 API 呼叫 — setSignature(certInfo: $cert, level: SignatureLevel::PAdES_B_B)
Union/intersection types	精確的參數型別貫穿整個 API
DNF types	用於內部驗證的複雜型別約束
#[\SensitiveParameter]	密碼和私鑰永遠不會出現在堆疊追蹤中（Aes256Encryptor、CertificateInfo、TsaClient）
#[\NoDiscard]	若忽略關鍵方法的回傳值，編譯器會發出警告（FontManager::registerFont()、FormFlattener::flatten()）
Property hooks	乾淨的 getter/setter 模式，不需要樣板程式碼
Pipe operator	簡化內部的資料轉換流程
Fibers	為佇列工作中的非同步 PDF 生成奠定基礎

「可是我的伺服器跑的是 PHP 8.1...」

使用 Docker 作為隔離層。你的應用程式可以跑任何 PHP 版本——TCPDF-Next 則在容器內執行。

最小化 Dockerfile

FROM php:8.5-cli

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

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

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

團隊協作的 Docker Compose

services:
  pdf-generator:
    build: .
    volumes:
      - ./output:/app/output
    command: php generate-pdf.php

Laravel 搭配 Docker

如果你的 Laravel 應用程式跑的是 PHP 8.2，但需要 TCPDF-Next，可以將 PDF 生成作為微服務執行：

services:
  app:
    image: php:8.2-fpm
    # Your Laravel app

  pdf-service:
    build:
      context: ./pdf-service
      dockerfile: Dockerfile
    image: php:8.5-cli
    volumes:
      - shared-output:/output

volumes:
  shared-output:

或是透過 Laravel 的佇列系統，將 PDF 生成任務發派到 PHP 8.5 的 worker 上。

🐳 Docker for Legacy PHP Environments

對於無法升級正式環境 PHP 版本的團隊，Docker 是推薦的做法。PDF 生成流程是完全隔離的——讀取輸入、寫出 PDF 檔案、結束。沒有共享狀態，沒有相容性問題。

取捨考量

藉由要求 PHP 8.5+，TCPDF-Next 獲得了：

• 更精簡的程式碼 — 現代語言特性取代了數百行的變通寫法
• 更強的型別安全 — PHPStan level 8 零錯誤
• 更好的安全性 — #[\SensitiveParameter] 防止憑證資料洩漏到日誌中
• 不可變物件 — Readonly 類別消除了一整類的錯誤
• 自我描述的程式碼 — 列舉取代魔術字串，具名參數取代位置陣列

一套能為你服務未來十年的函式庫，理應建構在未來十年的語言特性之上。