核心函式速查
| 函式 | 用途 | 回傳值 | 注意事項 |
is_dir() | 檢查路徑是否為目錄 | bool | 回傳 false 可能是不存在、是檔案、無權限 |
mkdir() | 建立目錄 | bool | 預設不遞迴,需第三參數 true |
rmdir() | 刪除**空**目錄 | bool | 非空目錄會失敗 |
基本用法
$path = '/var/www/html/uploads/2024/01';
// 1. 檢查並建立 (遞迴)
if (!is_dir($path)) {
mkdir($path, 0755, true); // true = 遞迴建立父目錄
}
// 2. 封裝為可重用函式
function ensureDir(string $path, int $mode = 0755): bool {
if (is_dir($path)) return true;
return mkdir($path, $mode, true);
}
// 3. 實務:上傳目錄初始化
$uploadDir = __DIR__ . '/storage/uploads/' . date('Y/m/d');
ensureDir($uploadDir);
常見陷阱與解決
1. 權限問題
// 檢查可寫入
if (!is_writable(dirname($path))) {
throw new Exception("父目錄不可寫入: " . dirname($path));
}
// 共享主機常見:PHP 以不同用戶執行 (mod_php vs php-fpm)
// 解決:設定正確擁有者/群組、ACL、或用 0775 + 群組寫入
2. 競態條件
// 錯誤:TOCTOU (Time-of-check to time-of-use)
if (!is_dir($path)) mkdir($path); // 兩行之間可能被其他進程建立
// 正確:mkdir 失敗時檢查錯誤碼
if (!@mkdir($path, 0755, true) && !is_dir($path)) {
throw new Exception("建立目錄失敗: $path");
}
3. Windows 路徑分隔符
// 錯誤
mkdir('C:\www\uploads'); // \ 是跳脫字元!
// 正確
mkdir('C:/www/uploads'); // 正斜線跨平台通用
mkdir('C:\\www\\uploads'); // 雙反斜線
mkdir('C:' . DIRECTORY_SEPARATOR . 'www' . DIRECTORY_SEPARATOR . 'uploads');
遞迴刪除目錄 (含檔案)
function removeDirRecursive(string $dir): bool {
if (!is_dir($dir)) return false;
$items = new RecursiveIteratorIterator(
new RecursiveDirectoryIterator($dir, RecursiveDirectoryIterator::SKIP_DOTS),
RecursiveIteratorIterator::CHILD_FIRST // 先刪子項
);
foreach ($items as $item) {
$item->isDir() ? rmdir($item->getPathname()) : unlink($item->getPathname());
}
return rmdir($dir);
}
進階:串流包裝器與雲端儲存
// 統一介面操作本地/遠端
$fs = new League\Flysystem\Filesystem(new LocalAdapter(__DIR__ . '/storage'));
$fs->createDirectory('path/to/dir');
$fs->deleteDirectory('path/to/dir');
效能提示
is_dir 有快取 (realpath cache),大量檢查前可 clearstatcache()
- 避免在迴圈中重複
mkdir,預先建立好目錄樹
- 大量檔案操作考慮
parallel 擴展或背景任務