早期 PHP 專案常自行實作類別自動載入,importModule() 即為典型範例。現代 PHP(5.3+)已內建 spl_autoload_register() 並配合 Composer PSR-4 標準,本文分析傳統實作並對比現代最佳實務。
<?php
/**
* 導入模組檔案(傳統實作)
*
* @param string $classString 類別路徑字串,可用 "." 代替 "/"
* @param string $fileType 副檔名類型:class/inc/自訂
* @return bool|Exception 成功 true,失敗拋出例外或 exit
*/
function importModule($classString, $fileType = 'class') {
global $module_path; // 依賴全域變數 ❌
$filename = $module_path . strtr($classString, '.', '/');
switch ($fileType) {
case 'class': $filename .= '.class.php'; break;
case 'inc': $filename .= '.inc.php'; break;
default: $filename .= $fileType; break;
}
if (is_file($filename)) {
include_once($filename);
return true;
} else {
exit('class "' . strtr($classString, '.', '') . '" is not found.');
// 直接 exit() 終止腳本 ❌ 應拋出例外讓上層處理
}
}
?>
| 問題 | 影響 | 現代解法 |
|---|---|---|
依賴 $module_path 全域變數 | 耦合度高、難測試、命名空間汙染 | 注入配置、使用 Composer 自動載入 |
exit() 直接終止 | 無法優雅處理錯誤、阻斷測試 | 拋出 Exception 或回傳 false |
| 硬編碼副檔名對應 | 擴充性差 | PSR-4 對應命名空間到目錄 |
| 不支援命名空間 | 無法對應現代類別結構 | 完整支援 PSR-4 |
| 無快取機制 | 每次請求重複檢查檔案系統 | Composer 產生 classmap/快取 |
{
"autoload": {
"psr-4": {
"App\\": "src/",
"Vendor\\Package\\": "packages/package/src/"
},
"classmap": [
"legacy/" // 兼容舊式類別
],
"files": [
"helpers.php" // 全域函數
]
}
}
src/
├── Controllers/
│ └── UserController.php // namespace App\Controllers; class UserController
├── Models/
│ └── User.php // namespace App\Models; class User
└── Services/
└── EmailService.php // namespace App\Services; class EmailService
<?php require_once __DIR__ . '/vendor/autoload.php'; // 直接使用,自動載入 $user = new App\Models\User(); $controller = new App\Controllers\UserController(); $service = new App\Services\EmailService(); ?>
<?php
// bootstrap.php
spl_autoload_register(function ($class) {
// 將命名空間轉為路徑
$file = __DIR__ . '/src/' . str_replace('\\', '/', $class) . '.php';
if (is_file($file)) {
require_once $file;
return true;
}
return false;
});
// 兼容舊代碼
function importModule($classString, $fileType = 'class') {
$class = str_replace('.', '\\', $classString);
if (class_exists($class) || interface_exists($class) || trait_exists($class)) {
return true;
}
// 觸發自動載入
if (spl_autoload_call($class)) {
return true;
}
throw new Exception("Class $classString not found");
}
?>
<?php
// legacy_map.php
return [
'gapi.Account' => 'App\Services\Google\Account',
'utils.helpers' => 'App\Helpers\helpers',
// ...
];
// importModule 改為查表轉發
function importModule($classString, $fileType = 'class') {
$map = require __DIR__ . '/legacy_map.php';
$modernClass = $map[$classString] ?? ('App\\Legacy\\' . str_replace('.', '\\', $classString));
if (!class_exists($modernClass)) {
throw new Exception("Legacy class $classString not mapped");
}
return true;
}
?>
<?php
class ClassLoader {
private array $prefixes = [];
private array $fallbackDirs = [];
private bool $useCache = false;
private string $cacheFile = '';
public function addPsr4(string $prefix, string|array $paths): void {
$prefix = rtrim($prefix, '\\') . '\\';
$paths = (array)$paths;
foreach ($paths as $path) {
$this->prefixes[$prefix][] = rtrim($path, '/') . '/';
}
}
public function addFallbackDir(string $dir): void {
$this->fallbackDirs[] = rtrim($dir, '/') . '/';
}
public function register(bool $prepend = false): void {
spl_autoload_register([$this, 'loadClass'], true, $prepend);
}
public function loadClass(string $class): bool {
// PSR-4 查找
foreach ($this->prefixes as $prefix => $dirs) {
if (str_starts_with($class, $prefix)) {
$relative = substr($class, strlen($prefix));
$file = str_replace('\\', '/', $relative) . '.php';
foreach ($dirs as $dir) {
$fullPath = $dir . $file;
if (is_file($fullPath)) {
require_once $fullPath;
return true;
}
}
}
}
// Fallback 目錄查找
foreach ($this->fallbackDirs as $dir) {
$file = $dir . str_replace('\\', '/', $class) . '.php';
if (is_file($file)) {
require_once $file;
return true;
}
}
return false;
}
// 產生 classmap 快取(生產環境用)
public function generateCache(string $cacheFile): void {
$map = [];
// 掃描所有前綴目錄建立對應...
file_put_contents($cacheFile, 'addPsr4('App\\', __DIR__ . '/src');
$loader->addPsr4('Vendor\\Package\\', __DIR__ . '/packages/package/src');
$loader->addFallbackDir(__DIR__ . '/legacy');
$loader->register();
?>
composer dump-autoload -o 產生 classmapcomposer.lock 納入版控importModule() 代表 PHP 早期手動載入時代的產物。現代專案應全面採用 Composer PSR-4 自動載入,享受標準化、快取優化、生態相容等優勢。遷移策略可採漸進式:先建立自動載入器並存、建立舊類別對應表、逐步重構命名空間、最終移除舊機制。新專案直接使用 Composer 即可,無需自行造輪子。