Yii 框架類映射自動加載：Yii::$classMap 實戰指南

痛點

Yii 1.x 預設靠 Yii::import() 按路徑別名載入類，大量第三方庫需手動 import 或配置 import 數組，啟動開銷大、維護麻煩。

解決方案：Yii::$classMap

Yii 基類定義靜態屬性 $classMap，鍵為類名，值為文件路徑。框架自動加載器優先查找此映射，命中則直接 include，無需路徑解析。

配置位置：入口文件 index.php

<?php
require_once($yii);
$config = require(dirname(__FILE__).'/protected/config/main.php');

$app = Yii::createWebApplication($config);

// 類映射註冊（在 run() 之前）
Yii::$classMap = [
    'JPhpMailer' => Yii::getPathOfAlias('ext.phpmailer.JPhpMailer'),
    'PHPExcel'   => Yii::getPathOfAlias('ext.phpexcel.PHPExcel'),
    'Swift_Mailer' => Yii::getPathOfAlias('ext.swiftmailer.lib.Swift_Mailer'),
    // 更多...
];

$app->run();

使用效果

<?php
// 控制器/模型中直接 new，無需 Yii::import()
$mailer = new JPhpMailer();
$excel = new PHPExcel();
$swift = new Swift_Mailer($transport);

優勢對比

最佳實踐

1. 第三方庫統一放入 protected/extensions/，以廠商/库名為目錄
2. 入口文件集中註冊，或單獨 classmap.php 返回數組，Yii::$classMap = require('classmap.php');
3. Composer 專案：優先使用 vendor/autoload.php，Yii 1.x 可共存（Yii::registerAutoloader()）
4. 自動生成映射：部署腳本掃描 extensions/ 目錄下所有 *.php，提取類名生成映射表

自動生成腳本示例

<?php
// build_classmap.php
$dir = __DIR__ . '/protected/extensions';
$map = [];
$iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($dir));
foreach ($iterator as $file) {
    if ($file->isFile() && $file->getExtension() === 'php') {
        $source = file_get_contents($file->getPathname());
        if (preg_match_all('/^(class|interface|trait)\s+(\w+)/m', $source, $m)) {
            foreach ($m[2] as $class) {
                $rel = str_replace([$dir, '/', '.php'], ['', '.', ''], $file->getPathname());
                $map[$class] = Yii::getPathOfAlias('ext.' . $rel);
            }
        }
    }
}
file_put_contents(__DIR__ . '/classmap.php', '