PHP 反射機制實戰：動態實例化與類結構分析完整指南

反射核心類速查

場景一：依賴注入容器自動裝配

根據設定檔動態建立模組實例，並自動注入建構子/Setter 依賴。

介面與實作定義

interface Module { public function execute(); }

class FtpModule implements Module {
    public function setHost($host) { echo "FTP Host: $host\n"; }
    public function setUser($user) { echo "FTP User: $user\n"; }
    public function execute() { /* ... */ }
}

class PersonModule implements Module {
    public function setPerson(Person $person) { echo "Person: {$person->name}\n"; }
    public function execute() { /* ... */ }
}

class Person { public $name; public function __construct($name) { $this->name = $name; } }

自動裝配執行器

class ModuleRunner {
    private $configData = [
        'PersonModule' => ['person' => 'bob'],
        'FtpModule'    => ['host' => 'example.com', 'user' => 'anon'],
    ];
    private $modules = [];

    public function init() {
        $interface = new ReflectionClass('Module');
        foreach ($this->configData as $moduleName => $params) {
            $moduleClass = new ReflectionClass($moduleName);

            // 1. 驗證型別相容性
            if (!$moduleClass->isSubclassOf($interface)) {
                throw new Exception("模組 $moduleName 不實作 Module 介面");
            }

            // 2. 實例化（無參建構子）
            $module = $moduleClass->newInstance();

            // 3. 掃描所有 public 方法尋找 Setter
            foreach ($moduleClass->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
                $this->handleMethod($module, $method, $params);
            }
            $this->modules[] = $module;
        }
    }

    private function handleMethod($module, ReflectionMethod $method, array $params) {
        $name = $method->getName();
        $args = $method->getParameters();

        // 僅處理 setXxx() 單參數方法
        if (count($args) !== 1 || strncasecmp($name, 'set', 3) !== 0) return;

        $prop = strtolower(substr($name, 3)); // setHost -> host
        if (!isset($params[$prop])) return;

        $arg = $args[0];
        $typeClass = $arg->getClass(); // 取得型別宣告的類

        if ($typeClass === null) {
            // 純量型別直接注入
            $method->invoke($module, $params[$prop]);
        } else {
            // 物件型別：遞迴建構實例
            $method->invoke($module, $typeClass->newInstance($params[$prop]));
        }
    }
}

$runner = new ModuleRunner();
$runner->init();

場景二：執行期提取類原始碼

適用於代碼生成器、文件產生器、熱重載偵測等場景。

class ReflectionUtil {
    public static function getClassSource(ReflectionClass $class): string {
        $path = $class->getFileName();
        $lines = file($path);
        $start = $class->getStartLine() - 1; // 0-based
        $length = $class->getEndLine() - $class->getStartLine() + 1;
        return implode(array_slice($lines, $start, $length));
    }
}

// 使用範例
$className = 'Person';
$path = "../practice/{$className}.php";
if (!file_exists($path) || !class_exists($className)) {
    throw new Exception("類別不存在");
}
echo ReflectionUtil::getClassSource(new ReflectionClass($className));

進階技巧與注意事項

存取私有/受保護成員

$class = new ReflectionClass('SomeClass');
$prop = $class->getProperty('privateProp');
$prop->setAccessible(true); // 關鍵：繞過可見性限制
$value = $prop->getValue($instance);

動態建構帶參實例

$class = new ReflectionClass('DbConnection');
$instance = $class->newInstanceArgs(['host' => 'localhost', 'port' => 3306]);

註解解析

$method = new ReflectionClass('UserService')->getMethod('login');
$docComment = $method->getDocComment(); // 取得 /** ... */ 內容
// 配合 doctrine/annotations 解析 @Route、@Entity 等屬性

效能考量

• 反射涉及大量字串操作與內部結構遍歷，比直接呼叫慢 10-100 倍
• 生產環境建議：快取反射結果（如 ReflectionClass 實例、方法參數陣列）
• 大量實例化場景優先用 new $className(...$args) 而非 ReflectionClass::newInstanceArgs()

常見應用領域

1. 框架核心：路由解析、控制器實例化、中介軟體管線建構
2. ORM/ODM：實體映射、關聯載入、查詢建構器
3. 測試工具：Mock 物件生成、私有方法測試、資料提供者
4. 代碼生成：API 文件自動生成、DTO/VO 類別產生、GraphQL Schema 映射
5. 插件系統：動態發現與載入實作特定介面的類別