HOWTO · PHP
在 PHP 中查詢根目錄路徑
本教程介紹如何查詢 PHP 專案的根目錄路徑
本頁內容
PHP 應用程式中可能有好幾種路徑都被稱為「根目錄」。專案根目錄是應用程式視為基底的目錄;目前檔案所在目錄是某個 PHP 指令碼所在的位置;Web 文件根目錄則是 Web 伺服器為請求公開的目錄。這些路徑可能彼此不同。請依照要尋找的檔案選擇適用的路徑,不要假設某個運算式永遠會傳回專案根目錄。
以下範例假設專案位於 /var/www/html/project,頂層有 index.php,而 login.php 位於 master/。範例中的伺服器文件根目錄是 /var/www/html。這些都是示意路徑,並非在你的伺服器上測得的值。
區分專案根目錄與 Web 文件根目錄
專案根目錄是應用程式採用的慣例,不是 PHP 設定。這個目錄可能包含應用程式程式碼、設定及其他檔案。Web 文件根目錄由伺服器設定,決定公開提供哪些 Web 檔案。在此範例中,專案位於文件根目錄之下;但部署時,專案可能放在其他位置,也可能將公開子目錄設為文件根目錄。
請記住兩者的差異:__DIR__ 和 dirname() 會依據 PHP 檔案的位置推導路徑;$_SERVER['DOCUMENT_ROOT'] 則回報目前請求的伺服器設定。這些值都不會自動找出應用程式專屬的根目錄。
使用 __DIR__ 取得目前檔案所在目錄
__DIR__ 魔術常數會傳回它所在檔案的絕對目錄。在 master/login.php 中,它代表 /var/www/html/project/master,而不是 /var/www/html/project。它是依據指令碼所在位置解析,因此即使從另一個工作目錄引入該指令碼,值也不會改變。若要組合指令碼旁邊或其子目錄中的檔案路徑,可以使用它;必要時,再以 PHP 的路徑分隔符附加相對路徑。
請執行這個獨立範例。提供的執行紀錄中,PHP 檔案儲存在 /work,因此兩個運算式都解析為該目錄。範例中的程式碼與輸出文字保持原樣,其中的標籤仍為英文:
<?php
echo "Current file directory: ", __DIR__, PHP_EOL;
echo "Directory from __FILE__: ", dirname(__FILE__), PHP_EOL;
?>
Current file directory: /work
Directory from __FILE__: /work
__FILE__ 是目前檔案的完整路徑,而 dirname(__FILE__) 會傳回該檔案所在的目錄。因此,使用較舊的 PHP 程式碼時,後者是實用的替代寫法;__DIR__ 則更直接地表達了用途。
使用 dirname() 找出上層目錄
使用 dirname(),從已知檔案路徑取得其父目錄。以 master/login.php 中的 __FILE__ 為起點,呼叫一次會傳回 master 目錄;再套用一次,就會傳回專案目錄。在範例目錄結構中,結果分別是 /var/www/html/project/master 和 /var/www/html/project。巢狀呼叫能清楚呈現每一步,也不必依賴支援情況取決於 PHP 版本的選用 levels 引數。
這項操作會沿著路徑組成部分向上移動;它不會依名稱搜尋資料夾,也不會向下進入子目錄。如果專案目錄結構變更,所需的父目錄層數也可能隨之改變。請在程式碼附近記錄這層關係;若有許多檔案都需要這個路徑,可以在設定中定義專案專用的基底路徑。
使用 $_SERVER['DOCUMENT_ROOT'] 讀取 Web 伺服器的文件根目錄
在 Web 請求期間,$_SERVER['DOCUMENT_ROOT'] 會包含該伺服器設定的文件根目錄。在示意設定中,此值為 /var/www/html,而專案根目錄是 /var/www/html/project。只有在確實需要伺服器的公開 Web 根目錄時才使用此值,例如組合相對於該設定目錄的路徑。不要把它當作專案根目錄的另一種說法。
這個伺服器變數取決於請求環境與伺服器設定。在命令列指令碼中,它可能不存在或不適用;不同部署環境的設定也可能不同。若程式碼可能在 Web 請求以外執行,請確認此變數可用。如果需要的是專案路徑,而不是伺服器的公開目錄,請使用 __DIR__ 或已設定的應用程式基底路徑。
簡而言之,使用 __DIR__ 取得目前 PHP 檔案所在目錄,使用巢狀的 dirname() 呼叫抵達已知的上層目錄(例如專案目錄),只有在需要 Web 伺服器設定的文件根目錄時才讀取 $_SERVER['DOCUMENT_ROOT']。示意路徑僅供參考;請在指令碼實際執行的環境中確認部署專屬設定。