为什么选择 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 类消除了一整类的错误
• 自我描述的代码 — 枚举取代魔术字符串，具名参数取代位置数组

一套能为你服务未来十年的库，理应构建在未来十年的语言特性之上。