PHP Fatal error: Call-time pass-by-reference has been removed 完整解決方案

錯誤訊息解讀

Fatal error: Call-time pass-by-reference has been removed in /path/file.php on line 10

含義：在函數呼叫處使用 &$var 強制傳址已被移除（PHP 5.4+）。正確做法是在函數定義處宣告參數為引用。

錯誤 vs 正確寫法對照

三種修復策略

策略一：修正函數定義（推薦、根治）

// 修改前
function addPrefix($str) {
    $str = 'PREFIX_' . $str;
}
addPrefix(&$myVar); // Fatal error

// 修改後
function addPrefix(&$str) {  // 參數定義加 &
    $str = 'PREFIX_' . $str;
}
addPrefix($myVar); // 正常，呼叫端不需 &

策略二：臨時相容舊代碼 (php.ini)

; php.ini
allow_call_time_pass_reference = On
; 重啟 PHP-FPM/Apache 生效

⚠️ 警告：此選項 PHP 5.4 已移除，PHP 8 完全不支援。僅作為緊急過渡，必須盡快改用策略一。

策略三：重構為返回值（現代化）

// 引用修改副作用大，改為純函數回傳新值
function addPrefix(string $str): string {
    return 'PREFIX_' . $str;
}
$myVar = addPrefix($myVar); // 明確、可測試、無副作用

批次掃描與自動修復工具

# 1. 掃描專案中所有呼叫端 &
grep -rn "&\$\w+" --include="*.php" src/

# 2. 使用 Rector 自動重構 (需 composer require rector/rector --dev)
# rector.php
use Rector\Php54\Rector\FuncCall\RemoveCallTimePassByReferenceRector;
$services->set(RemoveCallTimePassByReferenceRector::class);

# 執行
vendor/bin/rector process src/ --dry-run  # 預覽
vendor/bin/rector process src/            # 執行修復

常見誤區

• 誤以為內建函數也需 &：sort()、array_push()、usort() 等內建函數參數在定義處已宣告引用，呼叫端絕不可加 &。
• 混淆「傳址呼叫」與「傳址定義」：PHP 僅支援定義端引用，呼叫端自 PHP 5.4 起語法錯誤。
• 忽略版本升級影響：PHP 5.3 → 5.4/7.x/8.x 升級時，此錯誤最集中爆發，建議升級前跑完整測試套件。

最佳實踐總結

1. 新代碼嚴禁呼叫端 &$var。
2. 需修改外部變數時，在函數簽名加 &，並加註 /** @param Type $var 修改說明 */。
3. 優先使用返回值、DTO、事件機制替代引用副作用。
4. CI 流水線加入 php -l 語法檢查 + Rector 自動修復。