PHPUnit 「Please no longer include PHPUnit/Framework.php」錯誤解決方案：依賴衝突與自動發現機制修復

錯誤現象

PHP Notice: Please no longer include "PHPUnit/Framework.php" in /usr/share/php/PHPUnit/Framework.php on line 50

執行 `phpunit unit/DBTest.php` 時出現，導致測試無法正常運行。

根本原因

PHPUnit 3.5+ 採用 **PSR-0/PSR-4 自動載入**，不再需要手動 `require 'PHPUnit/Framework.php'`。此錯誤通常由以下情況引起：

1. 專案程式碼或舊版測試基類 仍包含 `require_once 'PHPUnit/Framework.php'` 或 `require_once 'PHPUnit/Autoload.php'`。
2. PEAR 安裝的 PHPUnit 套件版本不一致：`PHPUnit` 核心版本與 `PHP_CodeCoverage`、`PHPUnit_MockObject` 等依賴版本錯位，導致舊版 `Framework.php` 被載入。
3. Composer 與 PEAR 並存：專案用 Composer 管理依賴，但系統全域仍有 PEAR 安裝的 PHPUnit，CLI 執行時載入順序衝突。

解決步驟 (按推薦順序)

方案一：全面改用 Composer 管理 (現代標準，強烈推薦)

# 1. 移除系統全域 PEAR 套件
sudo pear uninstall phpunit/PHPUnit phpunit/PHPUnit_MockObject phpunit/PHP_CodeCoverage phpunit/PHP_TokenStream phpunit/Text_Template phpunit/File_Iterator phpunit/PHP_Timer phpunit/DbUnit phpunit/PHPUnit_Selenium

# 2. 專案目錄初始化 Composer (若無)
composer require --dev phpunit/phpunit ^9.5  # 或 ^10.0 對應 PHP 8.1+

# 3. 執行使用 vendor 版本
./vendor/bin/phpunit unit/DBTest.php

# 4. phpunit.xml.dist 設定 bootstrap (自動載入)
# ...

方案二：若必須用 PEAR 全域安裝，修復版本一致性

# 1. 開啟 auto_discover (讓 PEAR 自動發現頻道)
sudo pear config-set auto_discover 1

# 2. 檢查已安裝套件版本
pear list -a -c pear.phpunit.de

# 3. 完整移除所有 phpunit 相關套件 (順序重要，有依賴提示時先移除被依賴者)
sudo pear uninstall phpunit/PHPUnit
sudo pear uninstall phpunit/PHPUnit_MockObject
sudo pear uninstall phpunit/PHP_CodeCoverage
sudo pear uninstall phpunit/PHP_TokenStream
sudo pear uninstall phpunit/File_Iterator
sudo pear uninstall phpunit/Text_Template
sudo pear uninstall phpunit/PHP_Timer
sudo pear uninstall phpunit/DbUnit
sudo pear uninstall phpunit/PHPUnit_Selenium

# 4. 重新安裝最新穩定版
sudo pear install pear.phpunit.de/PHPUnit

# 5. 驗證
phpunit --version
phpunit unit/DBTest.php

方案三：快速工作繞過 (不修復根因，僅暫時壓制)

在測試啟動檔案 (如 `bootstrap.php` 或 `phpunit.xml` 的 `bootstrap`) 最頂端加入：

<?php
// 抑制特定 Notice
error_reporting(E_ALL & ~E_NOTICE);
// 或針對性過濾
set_error_handler(function ($severity, $message) {
    if ($severity === E_NOTICE && str_contains($message, 'Please no longer include')) {
        return true; // 忽略
    }
    return false;
}, E_NOTICE);

不建議長期使用，會掩蓋其他合法 Notice。

常見遺留程式碼清理

檢查專案中是否存在：

grep -r "PHPUnit/Framework.php" --include="*.php" .
grep -r "PHPUnit/Autoload.php" --include="*.php" .

發現則移除，現代 PHPUnit 僅需 `vendor/autoload.php` (Composer) 或 PEAR 自動載入即可。

版本對照表 (避免錯位)

最佳實踐總結

1. 專案級依賴管理：全面採用 Composer，`require-dev: phpunit/phpunit`，執行 `./vendor/bin/phpunit`，避免全域環境汙染。
2. CI/CD 環境：同樣用 Composer 安裝，鎖定版本 `composer.lock`。
3. 升級策略：PHP 版本升級時同步升級 PHPUnit 主版本，參考上表對照。
4. 避免 PEAR：PEAR 安裝方式已不再維護，易發生版本錯位、路徑衝突。

結語

「Please no longer include PHPUnit/Framework.php」本質是**自動載入機制變更**與**版本錯位**的綜合結果。徹底移除 PEAR 全域安裝、改用 Composer 專案級管理、清理舊版 `require` 語句，即能從根本解決並獲得穩定、可重現的測試環境。