拒絕 include_once/require_once：APC 快取失效與效能陷阱深度解析

眾多 PHP 開發者習慣用 include_once/require_once 防止重複載入，但這在啟用 **APC/OPcache** 時會導致**額外檔案系統呼叫**，抵消 opcode 快取優勢，甚至觸發 Cannot redeclare class 致命錯誤。本文從 PHP 內核機制剖析根因，建議改用 include + 自動載入器。

include_once 內部執行流程

1. 嘗試解析絕對路徑：若成功，檢查 EG(included_files) 快取，命中則直接返回。
2. 開啟檔案：取得 opened_path（真實路徑，含 symlink 解析）。
3. 再次檢查 EG(included_files)：以 opened_path 為鍵查找，命中則返回。
4. 編譯執行：呼叫 compile_file（被 APC/OPcache 劫持，從快取讀取 opcode）。

**關鍵問題**：步驟 2 **必須開啟檔案** 才能取得 opened_path，這產生一次 **額外的 open() 系統呼叫**，APC 正是為避免此呼叫而設計快取機制。

APC include_once_override 嘗試與缺陷

APC 引入 apc.include_once_override=1，劫持 ZEND_INCLUDE_OR_EVAL opcode，嘗試用 stat() 解析路徑並改寫 opcode 為 include。但實作長期存在缺陷：

<?php
set_include_path("/tmp");
function a($arg = array()) {
    include_once("b.php");
}
a();
a(); // 觸發致命錯誤：Cannot redeclare class

b.php 含 class B {}。APC 錯誤判定未載入而改寫為 include，導致重複定義類別。

為何建議棄用 include_once

1. 效能損耗：每次 include_once 產生額外 open()/stat()，高併發下可觀。
2. 快取不穩：APC/OPcache 覆寫機制不完美，易產生難以重現的「類別重複定義」、「函數找不到」詭異錯誤。
3. 架構反模式：依賴 include_once 兜底，意味著**載入順序不受控、依賴關係不明確**，違反單一職責與依賴倒置原則。
4. 現代替代方案完善：Composer PSR-4 自動載入器 保證每個類別**只載入一次、按需載入、路徑解析零開銷**（快取 classmap），從根源解決問題。

最佳實踐：include + 自動載入

// composer.json
{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        },
        "files": ["src/helpers.php"] // 函數檔案
    }
}
// 執行 composer dump-autoload -o 生成優化 classmap

// 代碼中直接使用類別，零 include
use App\Service\UserService;
$userService = new UserService();

// 極少數需動態載入（插件系統）時，使用 include + 手動快取
$loaded = [];
function loadPlugin($name) {
    global $loaded;
    if (isset($loaded[$name])) return true;
    $file = __DIR__ . "/plugins/$name.php";
    if (file_exists($file)) {
        include $file; // 不用 _once
        $loaded[$name] = true;
        return true;
    }
    return false;
}

歷史專案遷移清單

1. 全域搜尋 include_once/require_once。
2. 若為類別/介面/Trait → 納入 Composer 自動載入，刪除 include 行。
3. 若為函數/常數檔案 → 併入 autoload.files 或建立 bootstrap.php 統一 require（不需 _once）。
4. 執行測試套件、壓測驗證無回歸、效能提升。

使用 include_once 只能證明你對自己的代碼架構沒信心。 擁抱自動載入，擁抱確定性與效能。