PHP8.1环境下FPDI继承TCPDF失败、TCPDF常量加载异常问题

运行环境配置 #

• TCPDF版本：6.4.4
• FPDI版本：2.3.6
• PHP版本：8.1.7，部署在Windows Server 2012系统的Apache服务上，为开发环境
• 额外依赖：通过Composer安装naitsirch/tcpdf-extension（dev-master版本），项目接入Java/PHP桥接组件（该组件会修改报错输出形式，经排查不是问题根因）

Composer依赖配置 #

{
    "require": {
        "tecnickcom/tcpdf": "6.4.4",
        "setasign/fpdi": "^2.0",
        "naitsirch/tcpdf-extension": "dev-master"
    }
}

异常现象 #

原有代码在PHP5.6搭配旧版TCPDF（6.2.11）、FPDI（1.4.2）环境下运行正常，升级PHP至8.1.7并同步更新依赖库后出现两类异常：

1. 单独使用TCPDF时，TCPDF_static.php中定义的USLETTER等内置常量无法自动加载，手动定义对应常量后TCPDF可正常生成PDF
2. FPDI无法继承TCPDF，触发致命错误，报错信息如下：

PHP Fatal error:  During class fetch: Uncaught Error: Call to a member function invokeBegin()
 on null in http://127.0.0.1:8080/JavaBridge/java/Java.inc:557
Stack trace:
#0 http://127.0.0.1:8080/JavaBridge/java/Java.inc(56): java_Client->invokeMethod(0, 'typeExists', Array)
#1 C:\Program Files (x86)\PHP\v8.1\vendor\setasign\fpdi\src\Tcpdf\Fpdi.php(33):
 java_autoload_function('setasign\\Fpdi\\F...')
...
#8 {main} in C:\Program Files (x86)\PHP\v8.1\vendor\setasign\fpdi\src\Tcpdf\Fpdi.php on line 33

报错触发点为setasign\fpdi\src\Tcpdf\Fpdi.php第33行代码：class Fpdi extends \TCPDF。实际触发逻辑为：PHP类加载失败时，Java/PHP桥接的自动加载器作为兜底逻辑尝试加载对应Java类，因目标并非Java类才触发空对象调用错误，Java桥接本身不是问题根源。

业务相关代码 #

类定义代码 #

define("COMPOSER_AUTOLOADER","C:\\Program Files (x86)\\PHP\\v8.1\\vendor\\autoload.php");
require_once(COMPOSER_AUTOLOADER);
use setasign\Fpdi\Tcpdf\Fpdi;
class PDF extends Fpdi {
// 自定义业务方法
}

类调用代码 #

// initiate PDF
$pdf = new PDF($data['orientation'], 'mm', USLETTER, true, 'UTF-8', false);
$pdf->setPrintHeader(false);
$pdf->setPrintFooter(false);
$pdf->SetDefaultMonospacedFont(PDF_FONT_MONOSPACED);
$pdf->SetDisplayMode('real');
$pdf->SetAutoPageBreak(true, 1);

//set margins
$pdf->SetMargins(0,0);
$pdf->SetHeaderMargin(0);
$pdf->SetFooterMargin(0);
// ...其他业务逻辑
$pdf->AddPage($data['orientation']);
// ...其他业务逻辑
$pdf->Output('newpdf.pdf', 'I');

常量异常验证代码 #

require_once("C:\\Program Files (x86)\\PHP\\v8.1\\vendor\\autoload.php");
use setasign\Fpdi\Tcpdf\Fpdi;
define ('USLETTER',array(  612.000,   792.000));   
$pdf = new TCPDF('', 'in', USLETTER, true, 'UTF-8', false);
// ...其他PDF生成逻辑
$pdf->AddPage();
// ...其他PDF生成逻辑
$pdf->Output('newpdf.pdf', 'I');

问题根因 #

1. TCPDF内置常量无法自动加载 #

TCPDF从6.3.0版本开始调整了常量加载逻辑：所有页面尺寸、字体相关的全局常量不再像6.2.x版本那样直接写在TCPDF类入口文件中、随类加载自动定义，而是迁移到了TCPDF_STATIC类中，需要手动引入静态类文件并调用TCPDF_STATIC::loadConstants()方法才会完成常量的define操作。
如果代码中没有提前触发该静态方法，直接使用USLETTER这类常量就会报未定义错误。
另外安装的naitsirch/tcpdf-extension使用了dev-master分支，该分支长期未更新，兼容适配存在问题，其自带的自动加载配置会覆盖TCPDF原生的静态类加载规则，进一步阻断了常量的自动初始化流程。

2. FPDI无法继承TCPDF类 #

该问题是常量加载问题的连锁反应：
Composer的PSR-4自动加载规则在解析FPDI类时，需要先加载其父类\TCPDF，但上述两个问题导致TCPDF类没有被自动加载器正确识别为已加载状态。PHP会按照注册顺序逐个调用spl自动加载栈中的加载器尝试加载TCPDF类，由于Java/PHP桥接的自动加载器注册在Composer加载器之后，前序加载器加载失败后，桥接加载器会被触发，尝试去Java服务端查找同名类，最终抛出空对象调用的错误。
本质不是FPDI的继承语法存在问题，而是父类TCPDF未被正确加载，导致FPDI类解析失败，触发了兜底加载器的无关报错。

修复方案 #

1. 在引入Composer自动加载文件后、实例化PDF类之前，显式触发TCPDF常量加载：

require_once(COMPOSER_AUTOLOADER);
// 新增以下代码
$tcpdfPath = \Composer\InstalledVersions::getInstallPath('tecnickcom/tcpdf');
require_once($tcpdfPath . '/src/TCPDF_STATIC.php');
TCPDF_STATIC::loadConstants();

2. 移除或替换naitsirch/tcpdf-extension依赖：如果未使用该扩展的特殊功能直接移除即可；如果需要使用，不要用dev-master版本，更换为兼容TCPDF 6.4.x的稳定版本，避免其自动加载配置干扰原生TCPDF的加载流程。
3. 调整自动加载器注册顺序，将Composer自动加载器放到spl自动加载栈的最前端，确保Java桥接的加载器仅在所有PHP类加载逻辑执行完成后才作为兜底逻辑运行，避免类加载过程被桥接逻辑提前拦截。

内容的提问来源于stack exchange，提问作者starshine531