include_path 是 PHP 歷史上用於設定 include/require/fopen 等檔案操作函式「搜尋目錄清單」的設定指令。隨著 Composer PSR-4 自動載入成為標準,include_path 已逐漸退出歷史舞台,但理解其運作機制對維護舊專案、除錯載入問題、設計相容性庫仍有價值。
當呼叫 include 'file.php'(相對路徑、無 ./ ../ 前綴)時:
/、\\、C: 開頭)→ 是則直接載入。./、../ 開頭)→ 是則跳過 include_path,相對當前工作目錄 (cwd) 解析。include_path 中的目錄,拼接檔名嘗試載入,成功即返回。function find_file(string $filename): string|false {
if (is_absolute_path($filename)) return $filename;
if (is_relative_path($filename)) return resolve_cwd($filename); // ./ ../
$paths = explode(PATH_SEPARATOR, get_include_path());
$paths[] = dirname(current_executing_script()); // 當前腳本目錄
foreach ($paths as $dir) {
$full = $dir . DIRECTORY_SEPARATOR . $filename;
if (is_file($full)) return $full;
}
return false;
}
; Unix/Linux
include_path = ".:/usr/local/lib/php:/var/www/shared/lib"
; Windows
include_path = ".;C:\php\includes;D:\shared\lib"
ini_set()<?php
// 取得現有
$current = get_include_path(); // 字串
// 追加目錄(推薦用 PATH_SEPARATOR 跨平台)
ini_set('include_path', $current . PATH_SEPARATOR . '/var/www/shared/lib');
ini_set('include_path', $current . PATH_SEPARATOR . __DIR__ . '/../lib');
// 完全覆蓋
ini_set('include_path', implode(PATH_SEPARATOR, [
'.',
__DIR__ . '/../vendor/mylib',
'/usr/local/share/php',
]));
?>
-dphp -d include_path=".:/custom/lib" script.php
<?php
echo PATH_SEPARATOR; // Linux/macOS: ':' Windows: ';'
echo DIRECTORY_SEPARATOR; // Linux/macOS: '/' Windows: '\'
// 正確拼接路徑
$path = __DIR__ . DIRECTORY_SEPARATOR . 'lib' . DIRECTORY_SEPARATOR . 'config.php';
// 或直接用 '/'(PHP 內部自動正規化 Windows 路徑)
$path = __DIR__ . '/lib/config.php'; // 推薦:簡潔且跨平台安全
?>
<?php
// CakePHP bootstrap 簡化版
define('CAKE_CORE_INCLUDE_PATH', __DIR__ . '/../lib');
define('ROOT', dirname(__DIR__));
define('APP_DIR', 'src');
define('DS', DIRECTORY_SEPARATOR);
ini_set('include_path', implode(PATH_SEPARATOR, [
CAKE_CORE_INCLUDE_PATH,
ROOT . DS . APP_DIR,
get_include_path(), // 保留原有
]));
// 現在可直接:require 'Controller/AppController.php';
// 會依序在 core/lib、app/src、include_path 其餘目錄尋找
?>
include/require 相對路徑檔案,最壞情況掃描 N 個目錄(N = count(explode(PATH_SEPARATOR, get_include_path())))。lstat/stat 系統呼叫,磁碟 I/O 開銷大。include_path 目錄越多、越深、網路掛載越慢,效能越差。| 場景 | 原因 |
|---|---|
使用 ./file.php 或 ../file.php | 相對路徑前綴 → 直接解析 cwd,跳過 include_path |
使用絕對路徑 /full/path/file.php | 直接載入,不搜尋 |
__DIR__ . '/file.php' | 編譯期解析為絕對路徑 |
| 類別自動載入 (spl_autoload_register) | 走自動載入器堆疊,不經 include_path |
| PHAR 封裝 | 內部路徑解析獨立 |
<?php
// 臨時包裝器
function debug_include(string $file): bool {
$found = @include $file;
if ($found) {
$real = realpath($file);
error_log("INCLUDE: $file -> $real");
} else {
error_log("INCLUDE FAILED: $file (include_path=" . get_include_path() . ")");
}
return $found;
}
// 替換專案 include 呼叫或用 auto_prepend_file 注入
?>
composer dump-autoload -o --classmap-authoritative 生產環境極致優化。<?php
// bootstrap.php
define('ROOT', dirname(__DIR__, 2));
require ROOT . '/vendor/autoload.php'; // Composer
// 業務代碼
require ROOT . '/config/database.php';
$loader = new \App\Bootstrap();
?>
composer require myorg/shared-lib 自動進入 vendor,PSR-4 載入。include_path 依賴的共享庫。composer.json 引入套件,移除 ini_set('include_path')。require 'lib/foo.php' 為 use MyLib\Foo; 自動載入。include_path 設定。<?php
// tests/bootstrap.php
if (getenv('TEST_MODE')) {
// 將測試雙模擬庫注入 include_path 最前端
ini_set('include_path', __DIR__ . '/mocks' . PATH_SEPARATOR . get_include_path());
}
?>
| 維度 | include_path | Composer PSR-4 | 絕對路徑 require |
|---|---|---|---|
| 查找機制 | 執行期目錄遍歷 | 編譯期 Classmap O(1) 查找 | 直接載入 |
| 效能 | 低(多 stat 系統呼叫) | 極高 | 最高 |
| 可維護性 | 低(隱性依賴、順序敏感) | 高(宣告式、靜態分析友善) | 中(硬編碼路徑) |
| 跨專案共享 | 靠 include_path 串聯 | Composer 套件管理 | Git submodule / 符號連結 |
| 適用場景 | Legacy、極簡腳本、測試注入 | 現代所有專案 | 啟動引導、單檔腳本 |
include_path 是 PHP 早期解決「共享程式庫」的方案,但在 Composer + PSR-4 + Classmap 的現代工具鏈面前,已暴露出效能差、隱性依賴、除錯難、跨平台鬆散等缺陷。新專案零理由使用 include_path;舊專案應規劃遷移至 Composer 生態。理解其運作原理,僅為維護歷史代碼、除疑難雜症、設計相容層而服務。