自動載入是現代 PHP 專案的基石,讓類別檔案按需載入、免除手動 require。從早期的魔術函式 __autoload 到 SPL 標準化的 spl_autoload_register,再到 Composer + PSR-4 的生態標準,本文完整梳理演進歷程、API 詳解、多載入器管理、命名空間對應與框架整合實戰。
| 特性 | __autoload() (PHP 5.0+) | spl_autoload_register() (PHP 5.1.2+) |
|---|---|---|
| 定義方式 | 全域函式 | 註冊可呼叫物件至堆疊 |
| 數量限制 | 全域僅能存在一個 | 可註冊多個載入器,依序嘗試 |
| 彈性 | 低(單一入口) | 高(函式、靜態方法、實例方法、匿名函式、調用物件) |
| 優先序控制 | 無 | prepend=true 置頂 |
| 異常處理 | 難以統一 | 每個載入器可獨立拋出/捕獲 |
| 狀態 | PHP 7.2 棄用,8.0 移除 | 標準、持續維護 |
spl_autoload_register(
callable $autoload_function = null, // null 使用內建 spl_autoload(PSR-0 風格)
bool $throw = true, // 註冊失敗是否拋出例外
bool $prepend = false // true=置頂(優先嘗試),false=附加
): bool
spl_autoload 行為\\ 換成 /、附加 .php 或 .inc。include_path 中尋找。<?php
function myLoader(string $class): void {
// 專案根目錄
$base = __DIR__ . '/src/';
// 命名空間 \ 轉目錄分隔符
$file = $base . str_replace('\\', '/', $class) . '.php';
if (file_exists($file)) {
require_once $file;
}
// 找不到不拋錯,讓下一個載入器嘗試
}
spl_autoload_register('myLoader');
?>
<?php
class Autoloader {
private string $baseDir;
private string $namespacePrefix;
public function __construct(string $baseDir, string $namespacePrefix) {
$this->baseDir = rtrim($baseDir, '/') . '/';
$this->namespacePrefix = $namespacePrefix;
}
public function loadClass(string $class): void {
// 僅處理屬於此命名空間前綴的類別
if (!str_starts_with($class, $this->namespacePrefix)) {
return;
}
$relative = substr($class, strlen($this->namespacePrefix));
$file = $this->baseDir . str_replace('\\', '/', $relative) . '.php';
if (file_exists($file)) {
require_once $file;
}
}
}
// 註冊多個載入器對應不同命名空間
$loader1 = new Autoloader(__DIR__ . '/src', 'App\\');
$loader2 = new Autoloader(__DIR__ . '/vendor/foo', 'Foo\\');
spl_autoload_register([$loader1, 'loadClass']);
spl_autoload_register([$loader2, 'loadClass']);
// 或靜態方法
spl_autoload_register(['Autoloader', 'loadClassStatic']);
?>
<?php
spl_autoload_register(function (string $class): void {
$file = __DIR__ . '/lib/' . str_replace('\\', '/', $class) . '.php';
if (file_exists($file)) require_once $file;
});
?>
命名空間前綴 + 相對類別名。\\ 對應目錄分隔符,類別名對應 .php 檔案。{
"autoload": {
"psr-4": {
"App\\": "src/",
"App\\Tests\\": "tests/"
},
"files": ["src/helpers.php"] // 全域函式自動載入
},
"autoload-dev": {
"psr-4": {
"App\\Tests\\": "tests/"
}
}
}
vendor/autoload.php 註冊 Composer\Autoload\ClassLoader 實例。ClassLoader 實作 loadClass 方法,內建 PSR-4/PSR-0/Classmap 對應表(陣列查找,O(1))。composer dump-autoload -o 生成 Classmap(類別名→檔案路徑映射),載入速度最快。<?php
// 1. 專案核心載入器(優先)
spl_autoload_register([$appLoader, 'loadClass']);
// 2. 第三方庫載入器
spl_autoload_register([$vendorLoader, 'loadClass']);
// 3. 回退載入器(如 legacy 代碼)
spl_autoload_register('legacyLoader');
// 查看已註冊載入器
var_dump(spl_autoload_functions());
/*
array(3) {
[0] => array(2) { [0]=>object(AppLoader)#1 [1]=>string(9) "loadClass" }
[1] => array(2) { [0]=>object(VendorLoader)#2 [1]=>string(9) "loadClass" }
[2] => string(13) "legacyLoader"
}
*/
?>
prepend=true<?php
// 除錯用載入器:記錄所有載入嘗試
spl_autoload_register(function($class) {
error_log("Autoload attempt: $class");
}, true, true); // throw=true, prepend=true → 最優先執行
?>
| 問題 | 原因 | 解決 |
|---|---|---|
| Class not found | 命名空間/目錄對應錯誤、大小寫不符 | 檢查 composer dump-autoload、spl_autoload_functions() 追蹤 |
| 重複宣告錯誤 | 同類別被多個載入器載入 | 載入器內部 if (class_exists($class)) return; 或用 require_once |
| 效能差 | 大量 file_exists 系統呼叫 | 生產環境 composer dump-autoload -o 生成 Classmap |
| __autoload 失效 | 註冊 spl_autoload_register 後 __autoload 不再被呼叫 | spl_autoload_register('__autoload') 納入堆疊,或直接改寫 |
<?php
// 臨時註冊除錯載入器(置頂)
spl_autoload_register(function($class) {
$trace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 3);
error_log("AUTOLOAD: $class from " . ($trace[1]['function'] ?? 'unknown'));
}, true, true);
?>
Illuminate\Foundation\Application 繼承 ClassLoader。composer.json autoload 區塊定義 App\\ → app/。Kernel::registerBundles() 回傳 Bundle 陣列,各 Bundle 自帶 DependencyInjection 建立載入器。Composer\Autoload\ClassLoader 直接註冊 PSR-4 對應。composer dump-autoload -o --classmap-authoritative:生成權威 Classmap,跳過檔案系統檢查,效能最大化。src/Controller/UserController.php ↔ App\Controller\UserController。require。APCu 快取 Classmap(Composer 2.2+ 支援)。spl_autoload_register 確立了 PHP 自動載入的標準化基礎,Composer + PSR-4 將其昇華為生態系統標準。理解載入器堆疊機制、優先序控制、Classmap 最佳化與除錯技巧,能讓你在框架底層、套件開發、Legacy 遷移等場景遊刃有餘。