萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 魔術常數 __FILE__、__DIR__ 與 dirname() 路徑解析完整指南

前言

PHP 提供 9 個魔術常數,其中 __FILE__、__DIR__(PHP 5.3+)與 dirname() 函式是檔案路徑解析的核心工具。掌握它們在 include/require、符號連結、不同執行環境(CLI/Web)下的行為差異,對建構可攜式、安全的專案結構至關重要。

一、魔術常數速查表

常數說明回傳範例版本
__FILE__當前檔案完整絕對路徑(含檔名),解析符號連結/var/www/html/index.php4.0.2+ 絕對路徑
__DIR__當前檔案所在目錄絕對路徑(不含檔名,等同 dirname(__FILE__))/var/www/html5.3+
__LINE__當前行號1234.0+
__FUNCTION__函式名稱(區分大小寫,PHP 5+)myFunction4.3+
__CLASS__類別名稱(含命名空間,區分大小寫,PHP 5+)App\Models\User4.3+
__TRAIT__Trait 名稱(含命名空間)App\Traits\Loggable5.4+
__METHOD__類別方法名稱(含類別名)App\Models\User::getName5.0+
__NAMESPACE__當前命名空間名稱App\Models5.3+
ClassName::class類別完整限定名(編譯期解析)App\Models\User5.5+

二、__FILE__ 與 __DIR__ 深度解析

2.1 關係:__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 (相同)
?>

2.2 符號連結(Symlink)行為:真實路徑 vs 邏輯路徑


/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 或邏輯路徑。

2.3 include/require 內部的魔術常數:屬於「被包含檔案」

<?php
// main.php
require 'sub/config.php';

// sub/config.php
echo __FILE__; // /path/to/sub/config.php(當前執行檔案)
echo __DIR__;  // /path/to/sub
?>

三、dirname() 函式:層級向上導航

3.1 基礎用法

<?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
?>

3.2 專案根目錄定位模式

<?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');
?>

四、實戰應用場景

4.1 設定檔載入(相對專案根目錄)

<?php
// bootstrap.php
$configFile = CONFIG_PATH . '/database.php';
if (!file_exists($configFile)) {
    throw new RuntimeException("Config not found: $configFile");
}
return require $configFile; // 回傳陣列
?>

4.2 類別自動載入器基礎路徑

<?php
spl_autoload_register(function(string $class) {
    $file = ROOT_PATH . '/' . str_replace('\\', '/', $class) . '.php';
    if (file_exists($file)) require_once $file;
});
?>

4.3 模板/視圖路徑解析

<?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();
}
?>

4.4 安全:防止目錄遍歷攻擊

<?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);
}
?>

五、CLI vs Web 環境差異

場景__FILE__ / __DIR__getcwd()$_SERVER['SCRIPT_FILENAME']
Web 請求 index.php腳本實體路徑DocumentRoot腳本實體路徑
CLI php script.php腳本實體路徑當前工作目錄腳本實體路徑
CLI php -r '...'無(非檔案)當前工作目錄無
include 內部被包含檔案路徑不變主腳本路徑

建議:專案路徑基準永遠使用 __DIR__ 衍生,勿依賴 getcwd() 或 $_SERVER 變數。


六、現代 PHP 物件導向路徑處理:SplFileInfo

<?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 自動載入,路徑處理多集中於啟動引導階段,業務邏輯層盡量避免直接操作檔案路徑。

copyright © 萬盛學電腦網 all rights reserved