PHP 函式中使用 require_once 陷阱與優雅配置檔寫法

問題重現

配置檔 level.config.php 回傳陣列：

 '新手',
    2 => '進階',
    3 => '專家',
];

函式中使用 require_once 載入：

function getNameByLevel($level) {
    $level = intval($level);
    require_once 'level.config.php';  // 問題在這裡！
    
    if (!isset($config[$level])) {
        return false;
    }
    return $config[$level];
}

var_dump(getNameByLevel(1));  // string(6) "新手"
var_dump(getNameByLevel(2));  // bool(false) ← 錯誤！


原因分析

首次呼叫：require_once 載入檔案，$config 變數在函式區域作用域建立
第二次呼叫：require_once 偵測已載入，**不再執行檔案**，區域變數 $config 不存在 → 回傳 false


三種解決方案比較

方案一：全域載入 + global 關鍵字（不推薦）
require_once 'level.config.php';  // 全域載入

function getNameByLevel($level) {
    global $config;
    $level = intval($level);
    return $config[$level] ?? false;
}
缺點：汙染全域命名空間、未使用時仍載入、耦合度高

方案二：函式內 global + require_once（不推薦）
function getNameByLevel($level) {
    global $config;
    $level = intval($level);
    require_once 'level.config.php';
    return $config[$level] ?? false;
}
缺點：同樣汙染全域、程式碼雜亂

方案三：靜態類別配置（強力推薦）
 '新手',
        2 => '進階',
        3 => '專家',
    ];
}

function getNameByLevel($level) {
    $level = intval($level);
    require_once 'config/LevelConfig.php';
    
    return LevelConfig::$levels[$level] ?? false;
}

// 使用
echo getNameByLevel(1);  // 新手
echo getNameByLevel(2);  // 進階

進階：單例模式配置管理器
configs[$name])) {
            $path = __DIR__ . "/config/{$name}.php";
            if (file_exists($path)) {
                $this->configs[$name] = require $path;
            } else {
                throw new Exception("配置檔不存在: {$name}");
            }
        }
        return $this->configs[$name];
    }
    
    public function get($name, $key = null, $default = null) {
        $config = $this->load($name);
        if ($key === null) return $config;
        return $config[$key] ?? $default;
    }
}

// 使用
$config = ConfigManager::getInstance();
echo $config->get('level', 1);        // 新手
echo $config->get('database', 'host'); // 127.0.0.1

現代框架最佳實踐

Laravel / ThinkPHP 6+ 環境變數
// .env
APP_LEVEL_1=新手
APP_LEVEL_2=進階

// config/level.php
return [
    'levels' => [
        1 => env('APP_LEVEL_1', '新手'),
        2 => env('APP_LEVEL_2', '進階'),
    ],
];

// 使用
config('level.levels.1');  // 新手

優點總結

方案
命名空間乾淨
延遲載入
型別安全
可測試
推薦度
require_once + global
❌
❌
❌
❌
★
靜態類別
✅
✅
✅
✅
★★★★☆
單例管理器
✅
✅
✅
✅
★★★★★
框架配置系統
✅
✅
✅
✅
★★★★★


核心原則

配置即程式碼：用 PHP 陣列/類別而非純文字檔
單一職責：每個配置檔只管一個領域
依賴注入：函式接收配置物件而非自行載入
型別提示：IDE 自動完成、靜態分析支援