ThinkPHP 3.x 常量完整參考手冊
ThinkPHP 3.x 定義三大類常量：**預定義常量 (框架核心邏輯)、路徑常量 (目錄結構)、系統常量 (運行時環境)**。熟悉這些常量能讓你在配置、路徑引用、環境判斷、模板輸出時寫出可移植、不硬編碼的代碼。
一、預定義常量 (不隨環境變化)
| 常量 | 值 | 用途 |
|---|
URL_COMMON | 0 | 普通 URL 模式 (?m=...&a=...) |
URL_PATHINFO | 1 | PATHINFO 模式 (/module/action/param/val) |
URL_REWRITE | 2 | REWRITE 模式 (需 Web Server rewrite 規則) |
URL_COMPAT | 3 | 兼容模式 (不支援 PATHINFO 時退化) |
HAS_ONE | 1 | 關聯定義：一對一 |
BELONGS_TO | 2 | 關聯定義：屬於 (反向一對一) |
HAS_MANY | 3 | 關聯定義：一對多 |
MANY_TO_MANY | 4 | 關聯定義：多對多 |
THINK_VERSION | 如 '3.2.3' | 框架版本號 |
二、路徑常量 (可重新定義以客製化目錄結構)
預設遵循 ThinkPHP 標準目錄結構。若需調整目錄，**務必在入口文件 index.php 中 define() 覆蓋**，而非修改核心檔。
| 常量 | 預設值 | 說明 |
|---|
CORE_PATH | THINK_PATH . 'Lib/' | 核心類庫目錄 |
EXTEND_PATH | THINK_PATH . 'Extend/' | 擴展目錄 |
MODE_PATH | EXTEND_PATH . 'Mode/' | 模式擴展目錄 |
ENGINE_PATH | EXTEND_PATH . 'Engine/' | 引擎擴展目錄 |
VENDOR_PATH | EXTEND_PATH . 'Vendor/' | 第三方類庫目錄 (Composer vendor 建議獨立) |
LIBRARY_PATH | EXTEND_PATH . 'Library/' | 擴展類庫目錄 |
COMMON_PATH | APP_PATH . 'Common/' | 專案公共目錄 (共用函數/配置) |
LIB_PATH | APP_PATH . 'Lib/' | 專案類庫目錄 (Model/Action/Widget...) |
RUNTIME_PATH | APP_PATH . 'Runtime/' | 運行時目錄 (快取/日誌/編譯/Session/資料快取) |
CONF_PATH | APP_PATH . 'Conf/' | 專案配置目錄 |
LOG_PATH | RUNTIME_PATH . 'Logs/' | 日誌目錄 |
CACHE_PATH | RUNTIME_PATH . 'Cache/' | 模板快取目錄 |
LANG_PATH | APP_PATH . 'Lang/' | 語言包目錄 |
TEMP_PATH | RUNTIME_PATH . 'Temp/' | 臨時快取目錄 |
DATA_PATH | RUNTIME_PATH . 'Data/' | 資料快取目錄 (字段快取等) |
TMPL_PATH | APP_PATH . 'Tpl/' | 模板目錄 |
HTML_PATH | APP_PATH . 'Html/' | 靜態快取目錄 |
三、系統常量 (隨環境/請求/配置動態產生)
| 常量 | 說明 |
|---|
IS_CGI | 是否 CGI 模式 (FastCGI/PHP-FPM) |
IS_WIN | 是否 Windows 環境 |
IS_CLI | 是否命令列模式 (CLI) |
__ROOT__ | 網站根目錄 URL (如 https://domain.com 或 https://domain.com/subdir) |
__APP__ | 當前入口文件 URL (如 https://domain.com/index.php) |
__GROUP__ | 當前分組 URL |
__URL__ | 當前模組 (控制器) URL |
__ACTION__ | 當前操作 (方法) URL |
__SELF__ | 當前完整 URL (含查詢字串) |
__INFO__ | 當前 PATH_INFO 字串 |
APP_NAME | 當前專案名 |
GROUP_NAME | 當前分組名 |
MODULE_NAME | 當前模組名 (控制器名) |
ACTION_NAME | 當前操作名 (方法名) |
APP_DEBUG | 是否開啟調試模式 (布爾) |
MODE_NAME | 當前模式名稱 (如 common, api, cli) |
APP_PATH | 當前專案物理路徑 |
THINK_PATH | 框架核心物理路徑 |
MEMORY_LIMIT_ON | 記憶體統計支援是否開啟 |
RUNTIME_FILE | 專案編譯快取檔案名 |
THEME_NAME | 當前主題名稱 |
THEME_PATH | 當前模板主題物理路徑 |
APP_TMPL_PATH | 當前模板 URL 路徑 |
LANG_SET | 當前瀏覽器語言 (如 zh-cn) |
MAGIC_QUOTES_GPC | get_magic_quotes_gpc() 結果 |
四、實戰應用範例
1. 入口文件客製化路徑
// index.php
define('APP_PATH', __DIR__ . '/Application/');
define('RUNTIME_PATH', __DIR__ . '/Runtime/');
define('CONF_PATH', APP_PATH . 'Conf/');
// ... 其他需調整的路徑常量
require THINK_PATH . 'ThinkPHP.php';
2. 模板中輸出資源路徑
<link rel="stylesheet" href="__ROOT__/Public/css/app.css" />
<script src="__ROOT__/Public/js/app.js"></script>
<img src="__ROOT__/Public/images/logo.png" />
3. 代碼中判斷環境
if (IS_CLI) { /* 命令列腳本邏輯 */ }
if (IS_WIN) { /* Windows 路徑分隔符處理 */ }
if (APP_DEBUG) { /* 開發環境才輸出的調試資訊 */ }
4. 獲取當前控制器/方法
$module = MODULE_NAME; // 或 CONTROLLER_NAME (別名)
$action = ACTION_NAME;
$group = GROUP_NAME; // 分組模式下
五、常見誤區提醒
- 不要在代碼中硬編碼
/Application/Home/Controller/，改用 LIB_PATH、MODULE_NAME 動態拼裝。
__ROOT__ 不包含 index.php (REWRITE 模式下)，生成 URL 時配合 U() 函數自動處理。RUNTIME_PATH 必須可寫，部署時 chmod -R 775 Runtime/ 並設正確擁有者。- 常量區分大小寫，且全大寫下劃線命名。
