PHP 魔術方法全景圖：從 __construct 到 __serialize 的完整指南

PHP 中以雙下劃線 __ 開頭的類方法被稱為「魔術方法」，它們在特定生命週期節點被自動調用，賦予物件「智能行為」。掌握全套魔術方法，是進階 PHP 面向對象開發的必修課。本文系統梳理 16 個魔術方法的觸發時機、參數、返回值與實戰場景。

魔術方法速查總表

核心分組詳解與代碼示例

1. 生命週期三大件：構造、析構、克隆

<?php
class User {
    public $name;
    private $db;
    public $id;

    public function __construct($name) {
        $this->name = $name;
        $this->db = new PDO('mysql:host=localhost;dbname=test', 'user', 'pass');
        $this->id = uniqid();
        echo "__construct: 用戶 {$this->name} 初始化\n";
    }

    public function __destruct() {
        $this->db = null; // 關閉連接
        echo "__destruct: 用戶 {$this->name} 銷毀\n";
    }

    public function __clone() {
        $this->id = uniqid(); // 重置唯一標識
        $this->db = clone $this->db; // 深拷貝資源（若支持）
        echo "__clone: 用戶 {$this->name} 複製，新 ID: {$this->id}\n";
    }
}

$u1 = new User('Alice');
$u2 = clone $u1; // 觸發 __clone
unset($u1);      // 觸發 __destruct
?>

2. 屬性重載四件套：__get/__set/__isset/__unset

<?php
class Entity {
    private $data = [];
    private $dirty = [];

    public function __set($name, $value) {
        // 自動去除首尾空格、類型轉換
        $this->data[$name] = trim((string)$value);
        $this->dirty[$name] = true;
        echo "__set: {$name} = {$value}\n";
    }

    public function __get($name) {
        echo "__get: 讀取 {$name}\n";
        return $this->data[$name] ?? null;
    }

    public function __isset($name) {
        return isset($this->data[$name]);
    }

    public function __unset($name) {
        unset($this->data[$name], $this->dirty[$name]);
        echo "__unset: 刪除 {$name}\n";
    }

    public function getDirty() { return $this->dirty; }
}

$e = new Entity();
$e->name = '  Tom  ';  // __set 自動 trim
echo $e->name;         // __get 輸出 Tom
var_dump(isset($e->name)); // __isset true
unset($e->name);       // __unset
var_dump(isset($e->name)); // __isset false
?>

3. 方法重載：__call/__callStatic

<?php
class Router {
    public function __call($method, $args) {
        // 動態路由：$router->getUsers(['id'=>1]) -> handle('GET', 'users', ...)
        $httpMethod = strtoupper(substr($method, 0, 3)); // get, post, put, del
        $resource = strtolower(substr($method, 3));
        return $this->handle($httpMethod, $resource, $args[0] ?? []);
    }

    public static function __callStatic($method, $args) {
        // 靜態工廠：User::findById(1) -> find('id', 1)
        $action = strtolower(substr($method, 0, 3)); // fin, get, cre
        $field = strtolower(substr($method, 3));
        return (new static)->{$action}($field, $args[0] ?? null);
    }

    private function handle($method, $resource, $params) {
        return "Handling {$method} {$resource} with " . json_encode($params);
    }
}

$router = new Router();
echo $router->getUsers(['id' => 1]);      // __call
echo Router::findByName('Alice');         // __callStatic
?>

4. 序列化新舊 API 對比（PHP 7.4+ 推薦新 API）

<?php
class User {
    public $name;
    private $password; // 敏感字段不序列化
    private $db;       // 資源不序列化
    public $lastLogin;

    // 舊 API (PHP < 7.4)
    public function __sleep() {
        return ['name', 'lastLogin']; // 只序列化這兩個
    }
    public function __wakeup() {
        $this->db = new PDO(...); // 重建連接
        $this->password = null;   // 敏感字段置空
    }

    // 新 API (PHP 7.4+) - 更強大、類型安全、支持介面
    public function __serialize(): array {
        return [
            'name' => $this->name,
            'lastLogin' => $this->lastLogin,
        ];
    }
    public function __unserialize(array $data): void {
        $this->name = $data['name'];
        $this->lastLogin = $data['lastLogin'];
        $this->db = new PDO(...);
        $this->password = null;
    }
}

$user = new User();
$user->name = 'Bob';
$user->lastLogin = time();
$s = serialize($user); // 使用新 API
$u2 = unserialize($s);
?>

5. __invoke：讓物件像函數一樣調用

<?php
class Middleware {
    private $next;

    public function __construct(callable $next = null) {
        $this->next = $next;
    }

    public function __invoke(Request $req, Response $res) {
        echo "Middleware 執行前\n";
        if ($this->next) {
            ($this->next)($req, $res); // 調用下一個中間件
        }
        echo "Middleware 執行後\n";
    }
}

// 構建中間件鏈
$chain = new Middleware(
    new Middleware(
        new Middleware(function($req, $res) { echo "核心處理\n"; })
    )
);
$chain(new Request(), new Response()); // 像函數一樣調用
?>

6. __debugInfo：調試輸出可視化

<?php
class ApiToken {
    public $token;
    public $expiresAt;
    private $secretKey = 'super-secret';

    public function __debugInfo() {
        return [
            'token' => substr($this->token, 0, 8) . '***', // 脫敏
            'expiresAt' => $this->expiresAt,
            'isValid' => $this->expiresAt > time(),
            // secretKey 完全隱藏
        ];
    }
}

$t = new ApiToken();
$t->token = 'abcdefghijklmnopqrstuvwxyz';
$t->expiresAt = time() + 3600;
var_dump($t);
/*
object(ApiToken)#1 (3) {
  ["token"]=> string(11) "abcdefgh***"
  ["expiresAt"]=> int(1700000000)
  ["isValid"]=> bool(true)
}
*/
?>

最佳實踐原則

1. 慎用 __call/__get 等動態特性：降低代碼可讀性、IDE 提示失效、靜態分析工具報錯。僅在框架核心、代理模式、動態路由等場景使用。
2. 序列化優先用新 API (__serialize/__unserialize)：類型聲明、介面規範、不依賴屬性可見性、更安全。
3. __toString 必須返回 string：否則拋出 Error（PHP 7.4+）或 E_RECOVERABLE_ERROR。
4. __clone 做深拷貝：引用類型屬性（物件、資源、陣列）必須手動 clone，否則共享同一實例導致數據污染。
5. __destruct 不要拋出異常：析構階段異常會被忽略並產生警告，導致難以排查。
6. 敏感數據隱藏：利用 __debugInfo、__serialize 過濾密鑰、密碼、Token 等敏感字段。

總結

16 個魔術方法覆蓋了物件生命週期的每個關鍵節點。理解其觸發機制、參數約束、返回值要求，能讓你寫出更優雅、更安全、更具表達力的物件導向代碼。**現代 PHP 開發核心建議**：優先使用 __serialize/__unserialize 替代舊序列化 API，善用 __debugInfo 保護敏感信息，謹慎使用動態重載，拥抱類型聲明與靜態分析。