PHP 提供 9 個魔術常數,其中 __FILE__、__DIR__(PHP 5.3+)與 dirname() 函式是檔案路徑解析的核心工具。掌握它們在 include/require、符號連結、不同執行環境(CLI/Web)下的行為差異,對建構可攜式、安全的專案結構至關重要。
| 常數 | 說明 | 回傳範例 | 版本 |
|---|---|---|---|
__FILE__ | 當前檔案完整絕對路徑(含檔名),解析符號連結 | /var/www/html/index.php | 4.0.2+ 絕對路徑 |
__DIR__ | 當前檔案所在目錄絕對路徑(不含檔名,等同 dirname(__FILE__)) | /var/www/html | 5.3+ |
__LINE__ | 當前行號 | 123 | 4.0+ |
__FUNCTION__ | 函式名稱(區分大小寫,PHP 5+) | myFunction | 4.3+ |
__CLASS__ | 類別名稱(含命名空間,區分大小寫,PHP 5+) | App\Models\User | 4.3+ |
__TRAIT__ | Trait 名稱(含命名空間) | App\Traits\Loggable | 5.4+ |
__METHOD__ | 類別方法名稱(含類別名) | App\Models\User::getName | 5.0+ |
__NAMESPACE__ | 當前命名空間名稱 | App\Models | 5.3+ |
ClassName::class | 類別完整限定名(編譯期解析) | App\Models\User | 5.5+ |
__DIR__ === dirname(__FILE__)<?php
// 檔案:/var/www/html/project/config/database.php
echo __FILE__; // /var/www/html/project/config/database.php
echo __DIR__; // /var/www/html/project/config
echo dirname(__FILE__); // /var/www/html/project/config (相同)
?>
/var/www/html/project/ # 實體專案
/var/www/html/current -> project # 符號連結
// 在 current/config.php 中
echo __FILE__; // /var/www/html/project/config.php (解析後真實路徑)
echo __DIR__; // /var/www/html/project
關鍵:魔術常數總是回傳解析符號連結後的真實物理路徑,而非 URL 或邏輯路徑。
<?php
// main.php
require 'sub/config.php';
// sub/config.php
echo __FILE__; // /path/to/sub/config.php(當前執行檔案)
echo __DIR__; // /path/to/sub
?>
<?php
$path = '/var/www/html/project/config/database.php';
echo dirname($path); // /var/www/html/project/config
echo dirname($path, 2); // /var/www/html/project (PHP 7.0+ 支援層級)
echo dirname($path, 3); // /var/www/html
?>
<?php
// 傳統寫法(相容舊版)
$root = dirname(dirname(__FILE__));
// PHP 7.0+ 現代寫法
$root = dirname(__DIR__, 2); // 向上 2 層
// 定義常數供全專案使用
define('ROOT_PATH', dirname(__DIR__, 2));
define('CONFIG_PATH', ROOT_PATH . '/config');
define('PUBLIC_PATH', ROOT_PATH . '/public');
?>
<?php
// bootstrap.php
$configFile = CONFIG_PATH . '/database.php';
if (!file_exists($configFile)) {
throw new RuntimeException("Config not found: $configFile");
}
return require $configFile; // 回傳陣列
?>
<?php
spl_autoload_register(function(string $class) {
$file = ROOT_PATH . '/' . str_replace('\\', '/', $class) . '.php';
if (file_exists($file)) require_once $file;
});
?>
<?php
function view(string $name, array $data = []): string {
$file = VIEW_PATH . '/' . str_replace('.', '/', $name) . '.php';
if (!file_exists($file)) throw new InvalidArgumentException("View not found: $name");
extract($data);
ob_start();
require $file;
return ob_get_clean();
}
?>
<?php
function safeRead(string $userInput): string {
$base = REAL_DATA_PATH; // 實際資料目錄絕對路徑
$requested = realpath($base . '/' . $userInput);
// 確保解析後路徑在基礎目錄內
if ($requested === false || strpos($requested, $base) !== 0) {
throw new InvalidArgumentException('Invalid path');
}
return file_get_contents($requested);
}
?>
| 場景 | __FILE__ / __DIR__ | getcwd() | $_SERVER['SCRIPT_FILENAME'] |
|---|---|---|---|
Web 請求 index.php | 腳本實體路徑 | DocumentRoot | 腳本實體路徑 |
CLI php script.php | 腳本實體路徑 | 當前工作目錄 | 腳本實體路徑 |
CLI php -r '...' | 無(非檔案) | 當前工作目錄 | 無 |
| include 內部 | 被包含檔案路徑 | 不變 | 主腳本路徑 |
建議:專案路徑基準永遠使用
__DIR__衍生,勿依賴getcwd()或$_SERVER變數。
<?php
$file = new SplFileInfo(__FILE__);
echo $file->getRealPath(); // 真實路徑
echo $file->getPath(); // 目錄
echo $file->getBasename(); // 檔名
echo $file->getExtension(); // 副檔名
echo $file->isFile(); // true
echo $file->getSize(); // 大小
echo $file->getMTime(); // 修改時間
// 目錄遍歷
$dir = new RecursiveDirectoryIterator(__DIR__);
$iter = new RecursiveIteratorIterator($dir);
foreach ($iter as $file) {
if ($file->isFile() && $file->getExtension() === 'php') {
echo $file->getPathname() . "\n";
}
}
?>
| 錯誤寫法 | 問題 | 正確寫法 |
|---|---|---|
require 'config.php';(相對路徑) | 依賴 include_path/cwd,不穩定 | require __DIR__ . '/config.php'; |
dirname(__FILE__) . '/../config' | 字串拼接易錯、跨平台分隔符 | dirname(__DIR__, 2) . DIRECTORY_SEPARATOR . 'config' |
__DIR__ . 'config.php' | 缺少分隔符 | __DIR__ . '/config.php' |
假設 __DIR__ 有尾斜線 | 無尾斜線 | 統一用 rtrim(__DIR__, '/') . '/' 或直接拼接 /(PHP 跨平台支援) |
__FILE__、__DIR__、dirname() 組成 PHP 路徑解析鐵三角。核心原則:**以 __DIR__ 為錨點、向上導航定位專案根目錄、向下拼接具體資源、善用 realpath() 規範化、嚴防目錄遍歷**。現代專案配合 Composer PSR-4 自動載入,路徑處理多集中於啟動引導階段,業務邏輯層盡量避免直接操作檔案路徑。