PHP 魔術常數完整指南

魔術常數是 PHP 預定義常數，其值隨代碼位置動態變化，不區分大小寫。共八個，提供除錯、日誌、路徑解析、反射等關鍵資訊。本文詳細解析各常數行為與實務應用。

八大魔術常數總覽

詳細解析與範例

1. __LINE__ - 當前行號

<?php
echo "這是第 " . __LINE__ . " 行\n"; // 輸出行號
// 多行字串中以起始行為準
$str = "第 " . __LINE__ . " 行開始
第 " . __LINE__ . " 行結束";
?>

2. __FILE__ - 完整檔案路徑

<?php
echo __FILE__; 
// /var/www/html/project/src/Controller/UserController.php

// 包含檔案中返回被包含檔案路徑
// main.php: require 'config.php';
// config.php: echo __FILE__; // 顯示 config.php 路徑

3. __DIR__ - 檔案目錄

<?php
echo __DIR__; 
// /var/www/html/project/src/Controller

// 專案根目錄常用模式
define('ROOT_PATH', __DIR__ . '/../../');
// 或 PHP 7.0+
define('ROOT_PATH', dirname(__DIR__, 2));

4. __FUNCTION__ - 函數名稱

<?php
function processOrder() {
    echo __FUNCTION__; // "processOrder"
}

class OrderService {
    public function process() {
        echo __FUNCTION__; // "process" (不含類別名)
    }
}

// 閉包
$fn = function() { echo __FUNCTION__; }; // "{closure}"
$fn();

5. __CLASS__ - 類別名稱

<?php
namespace App\Models;

class User {
    public function getClass() {
        return __CLASS__; // "App\Models\User"
    }
    
    public static function getClassStatic() {
        return __CLASS__; // "App\Models\User"
    }
}

$user = new User();
echo $user->getClass();
echo User::getClassStatic();

// Trait 中使用
trait Loggable {
    public function log() {
        echo __CLASS__; // 使用此 Trait 的類別名
    }
}

class Article {
    use Loggable;
}
$article = new Article();
$article->log(); // "Article" (而非 Loggable)

6. __TRAIT__ - Trait 名稱

<?php
trait Timestampable {
    public function getTraitName() {
        return __TRAIT__; // "Timestampable"
    }
}

class Model {
    use Timestampable;
}

$model = new Model();
echo $model->getTraitName(); // "Timestampable"

// 命名空間下
namespace App\Traits;
trait SoftDeletes {
    public function traitName() { return __TRAIT__; } // "App\Traits\SoftDeletes"
}

7. __METHOD__ - 類別方法名稱

<?php
class UserService {
    public function create() {
        echo __METHOD__; // "UserService::create"
    }
    
    public static function find() {
        echo __METHOD__; // "UserService::find"
    }
}

echo __METHOD__; // 全域空間顯示為空字串或函數名

8. __NAMESPACE__ - 當前命名空間

<?php
namespace App\Http\Controllers;

echo __NAMESPACE__; // "App\Http\Controllers"

// 動態建構類別名
function makeModel(string $model): string {
    return __NAMESPACE__ . '\\Models\\' . $model;
}
// App\Http\Controllers\Models\User

實務應用場景

1. 除錯與日誌

<?php
function debugLog(string $message, array $context = []): void {
    $log = sprintf(
        "[%s] %s:%d %s() - %s",
        date('c'),
        basename(__FILE__),
        __LINE__,
        __FUNCTION__,
        $message
    );
    error_log($log . ' ' . json_encode($context, JSON_UNESCAPED_UNICODE));
}

debugLog('用戶登入', ['user_id' => 123, 'ip' => $_SERVER['REMOTE_ADDR']]);
// [2024-01-15T10:30:00+08:00] AuthController.php:45 login() - 用戶登入 {"user_id":123,"ip":"192.168.1.1"}

2. 自動載入器路徑解析

<?php
// 在 Composer vendor/autoload.php 或自訂載入器中
$baseDir = __DIR__ . '/../src/'; // 專案 src 目錄

3. 包含檔案相對路徑

<?php
// config.php 在專案根目錄
require_once __DIR__ . '/../config/database.php';

// 避免使用相對路徑 require '../config.php'（依賴當前工作目錄）

4. 動態類別實例化

<?php
namespace App\Factories;

function createController(string $name): object {
    $class = __NAMESPACE__ . '\\..\\Controllers\\' . $name . 'Controller';
    if (!class_exists($class)) {
        throw new InvalidArgumentException("Controller $name 不存在");
    }
    return new $class();
}

5. Trait 衝突偵測

<?php
trait A { public function test() { echo __TRAIT__ . "::test\n"; } }
trait B { public function test() { echo __TRAIT__ . "::test\n"; } }

class C {
    use A, B {
        A::test insteadof B;
        B::test as testB;
    }
}

$c = new C();
$c->test();  // A::test
$c->testB(); // B::test

常見誤區

效能注意

• 魔術常數在編譯時解析，執行期無額外開銷
• 大量除錯日誌建議條件編譯或關閉，避免 I/O 瓶頸
• __DIR__ 優於 dirname(__FILE__)（語意更清晰、效能相同）

魔術常數是 PHP 反射與元編程的基礎工具。熟練掌握其行為差異，能撰寫更健壯的載入器、除錯工具、日誌系統與動態架構元件。