ThinkPHP import() 類庫載入機制完整解析與五大用法

import() 核心功能

import() 是 ThinkPHP 的類庫自動載入入口，支援命名空間式路徑對應到實體檔案路徑，並內建單例快取避免重複載入。底層呼叫 Think::import() 解析路徑、載入檔案、實例化類別 (可選)。

五大標準用法詳解

1. 專案類庫載入 @.模組.類別

import('@.Common.Util.StringTool');
// 解析路徑：APP_PATH . 'Common/Util/StringTool.class.php'
// 適用：專案內自訂工具類、服務類、模型擴展

• @ 代表專案根目錄 (APP_PATH)
• 對應 Lib/ 目錄下的結構
• 類別檔案命名：類別名.class.php (區分大小寫)

2. 系統核心類庫載入 Think.模組.類別

import('Think.Util.Page');
// 解析路徑：THINK_PATH . 'Lib/Util/Page.class.php'
// 適用：框架內建分頁、驗證、快取、日誌等核心類

• Think 代表框架系統目錄 (THINK_PATH)
• 對應 ThinkPHP/Lib/ 目錄

3. 第三方/擴展類庫載入 ORG.類別 或 COM.類別

import('ORG.Util.Phpqrcode');      // 第三方開源類庫
import('COM.Payment.Alipay');      // 企業內部共用類庫

// 解析路徑：
// THINK_PATH . 'Extend/Library/ORG/Util/Phpqrcode.class.php'
// THINK_PATH . 'Extend/Library/COM/Payment/Alipay.class.php'

• ORG：Open Resource Group，第三方通用擴展 (如 PHPQRCode、PHPExcel、Markdown 解析器)
• COM：Component/Company，企業內部跨專案共用元件
• 目錄結構：ThinkPHP/Extend/Library/{ORG|COM}/

4. 分組/模組類庫載入 GroupName.模組.類別

import('Admin.User.Service');
// 解析路徑：APP_PATH . '../Admin/Lib/User/Service.class.php'
// 適用：多模組/分組架構下跨模組呼叫服務類

• 非 @、Think、ORG、COM 開頭，視為分組名稱
• 對應 APP_PATH/../{GroupName}/Lib/
• 需在配置啟用 APP_GROUP_LIST、APP_GROUP_MODE

5. 別名載入 import('alias_name')

步驟 1：定義別名檔案 Conf/alias.php

return [
    'StringTool'   => LIB_PATH . 'Common/Util/StringTool.class.php',
    'Phpqrcode'    => EXTEND_PATH . 'ORG/Util/Phpqrcode.class.php',
    'Alipay'       => EXTEND_PATH . 'COM/Payment/Alipay.class.php',
    'CustomClass'  => '/absolute/path/to/CustomClass.php', // 支援絕對路徑
];

步驟 2：直接使用別名

import('StringTool');    // 自動解析為 Conf/alias.php 定義路徑
import('Alipay');        // 簡潔、解耦實體路徑

import() 進階參數與行為

// 完整簽名
import($class, $baseUrl = '', $ext = '.class.php', $autoInstantiate = false);

/*
$class           : 類別標識 (支援上述 5 種格式)
$baseUrl         : 自訂基礎路徑 (留空自動判斷)
$ext             : 副檔名 (預設 .class.php，可改 .php)
$autoInstantiate : true = 載入後自動 new Class() 並回傳實例
                   false = 僅載入類別定義，回傳類別名稱字串
*/

// 範例：載入並實例化
$qr = import('ORG.Util.Phpqrcode', '', '.php', true);
// 等同於：
// require_once '.../Phpqrcode.php';
// $qr = new Phpqrcode();

// 範例：自訂基礎路徑載入專案外類別
$custom = import('MyClass', '/data/shared/libs/', '.php', true);

自動載入對比：import() vs spl_autoload_register

遷移建議：ThinkPHP 3 → 5/6/8

// TP3 import 用法
import('ORG.Util.Phpqrcode');
$qr = new Phpqrcode();

// TP5/6/8 Composer + 命名空間
// composer require endroid/qr-code
use Endroid\QrCode\QrCode;
$qr = new QrCode('https://example.com');

// 若必須保留舊類別，建立別名映射 (composer.json)
"autoload": {
    "classmap": ["ThinkPHP/Extend/Library/ORG/"]
    // 或 "files": ["ThinkPHP/Extend/Library/ORG/Util/Phpqrcode.php"]
}

常見錯誤與除錯

1. 類別未找到：檢查路徑大小寫 (Linux 區分大小寫)、副檔名 .class.php、目錄結構對應。
2. 重複宣告：import() 內建 import_list 快取，同一請求不會重複 require；但若手動 require_once 再 import() 可能衝突。
3. 命名空間衝突：舊類別無命名空間，新專案引入同名 Composer 套件會衝突。解決：重構舊類別加入命名空間、或用 class_alias 映射。
4. 效能問題：大量 import() 分散在控制器各處。優化：在公共控制器 _initialize() 或模型 _initialize() 集中載入常用類。