PHP 函數設計規範與最佳實踐：參數檢查、靜態變數、避免污染變數

PHP 函數開發規範與核心技巧總結

良好的函數設計能大幅提升代碼可維護性與健壯性。本文整理命名規範、參數驗證、靜態變數應用、引用陷阱等實戰經驗，助你寫出專業級函數。

一、函數命名規範建議

二、函數設計核心原則

1. 防禦性編程：函數開頭必驗證參數型別、空值、邊界值
2. 不污染原始參數：需修改時先複製，避免副作用影響呼叫端
3. 單一職責：一個函數只做一件事，拒絕萬用函數
4. 明確返回型別：PHP 7.0+ 善用返回型別宣告 : array、: string、: ?int
5. 文件化註解：標準 PHPDoc 格式，IDE 可自動提示

三、參數驗證範例：UTF-8 安全截取

/**
 * 安全截取 UTF-8 字串，支援中文
 * @param string $str 輸入字串
 * @param int $width 截取字元數（非位元組）
 * @param string $suffix 截斷後綴
 * @return string
 */
function str_cut_utf8(string $str, int $width = 0, string $suffix = '...'): string {
    // 1. 參數驗證
    if ($str === '' || $width <= 0) return $str;
    
    // 2. 不修改原參數
    $width = (int)$width;
    
    // 3. 核心邏輯
    $result = mb_strcut($str, 0, $width, 'UTF-8');
    
    // 4. 兜底處理
    if ($result === false || $result === '') return $str;
    
    return $result . $suffix;
}

// 測試
echo str_cut_utf8('我是開發者', 4); // 我是開...
echo str_cut_utf8('hello world', 5); // hello...
echo str_cut_utf8('', 10); // (空字串)
echo str_cut_utf8('test', -1); // test

四、靜態變數：跨呼叫保持狀態

function counter() {
    static $count = 0; // 僅初始化一次
    return ++$count;
}

echo counter(); // 1
echo counter(); // 2
echo counter(); // 3

// 實用場景：單例模式、快取、避免重複初始化
function get_db_config() {
    static $config = null;
    if ($config === null) {
        $config = parse_ini_file('/etc/app/db.ini');
    }
    return $config;
}

五、引用參數：慎用，理解副作用

function modify(&$val) {
    $val *= 2;
}

$a = 5;
modify($a);
echo $a; // 10 (原變數被修改)

// 危險範例：回傳引用
function &get_ref() {
    static $x = 0;
    return $x;
}

$ref = &get_ref();
$ref = 100;
echo get_ref(); // 100 (靜態變數被外部修改)

警告： PHP 5.3+ 棄用呼叫時傳址 call_user_func('func', &$var)，PHP 7+ 移除。現代寫法請在函數定義處宣告參考 function(&$param)。

六、不定參數：func_get_args() 與 ... 運算子

// PHP 5.6+ 寫法
function sum(...$numbers) {
    return array_sum($numbers);
}

echo sum(1,2,3,4,5); // 15

// 舊版相容寫法
function sum_legacy() {
    return array_sum(func_get_args());
}

七、避坑指南

• ❌ 使用大寫函數名 MY_FUNC()（易與常數混淆）
• ❌ 過度封裝：add($a,$b) 包裝 $a+$b
• ❌ 忽略錯誤處理：直接 mysql_query() 不檢查返回值
• ✅ 善用型別提示：function (int $id, string $name): array
• ✅ 早期返回：減少巢狀縮排
• ✅ 單元測試覆蓋核心函數