核心檔案系統函數速查
| 函數 | 用途 | 回傳值 |
is_dir() | 檢查是否為目錄 | bool |
is_file() | 檢查是否為檔案 | bool |
is_readable() | 檢查可讀 | bool |
is_writable() | 檢查可寫 | bool |
file_exists() | 檢查存在 | bool |
scandir() | 掃描目錄內容 | 陣列(含 . 與 ..) |
opendir()/readdir()/closedir() | 目錄控制代碼迭代 | resource/string/bool |
pathinfo() | 解析路徑資訊 | ['dirname','basename','extension','filename'] |
filemtime() | 最後修改時間(Unix 時間戳) | int|false |
filesize() | 檔案大小(位元組) | int|false |
realpath() | 取得絕對路徑(解析符號連結) | string|false |
範例 1:列出目錄下可讀寫的特定副檔名檔案
<?php
function listAllowedFiles(array $allowedExts, string $dir): void {
if (!is_dir($dir)) {
echo "目錄不存在: $dir\n";
return;
}
$files = scandir($dir);
foreach ($files as $file) {
if ($file === '.' || $file === '..') continue;
$path = $dir . DIRECTORY_SEPARATOR . $file;
if (!is_file($path)) continue; // 跳過子目錄
if (!is_readable($path) || !is_writable($path)) continue;
$info = pathinfo($path);
if (!isset($info['extension']) || !in_array(strtolower($info['extension']), $allowedExts)) {
continue;
}
echo $file . "\n";
}
}
listAllowedFiles(['txt', 'html', 'php'], __DIR__ . '/testfolder');
範例 2:遞迴列出目錄樹(含縮排顯示層級)
<?php
function printDirTree(string $dir, int $depth = 0): void {
$indent = str_repeat(' ', $depth);
if (!is_dir($dir)) {
echo "{$indent}[非目錄] $dir\n";
return;
}
$handle = @opendir($dir);
if (!$handle) {
echo "{$indent}[無權限] $dir\n";
return;
}
echo "{$indent}📁 " . basename($dir) . "\n";
while (($entry = readdir($handle)) !== false) {
if ($entry === '.' || $entry === '..') continue;
$path = $dir . DIRECTORY_SEPARATOR . $entry;
if (is_dir($path)) {
printDirTree($path, $depth + 1);
} else {
echo $indent . " 📄 $entry\n";
}
}
closedir($handle);
}
printDirTree(__DIR__ . '/testfolder');
範例 3:依最後修改時間排序檔案(新舊/舊新)
<?php
function getFilesSortedByMtime(string $dir, bool $desc = true): array {
if (!is_dir($dir)) return [];
$files = [];
foreach (scandir($dir) as $file) {
if ($file === '.' || $file === '..') continue;
$path = $dir . DIRECTORY_SEPARATOR . $file;
if (is_file($path)) {
$files[$path] = filemtime($path);
}
}
$desc ? arsort($files) : asort($files); // 保持路徑關聯
return $files;
}
$sorted = getFilesSortedByMtime(__DIR__ . '/testfolder', true); // 新→舊
foreach ($sorted as $path => $mtime) {
echo "File: $path | Modified: " . date('Y-m-d H:i:s', $mtime) . "\n";
}
現代物件導向替代方案:SplFileInfo / DirectoryIterator(PHP 5.3+)
<?php
// 遞迴迭代器:自動處理遞迴、過濾、排序
$iterator = new RecursiveIteratorIterator(
new RecursiveDirectoryIterator(__DIR__ . '/testfolder',
FilesystemIterator::SKIP_DOTS | FilesystemIterator::KEY_AS_PATHNAME),
RecursiveIteratorIterator::SELF_FIRST
);
// 過濾:僅 .php 檔案、大小 > 1KB、最近 7 天修改
$filter = new RegexIterator($iterator, '/\.php$/i');
$filter = new CallbackFilterIterator($filter, function($file) {
return $file->getSize() > 1024
&& $file->getMTime() > (time() - 7 * 86400);
});
// 排序需先收集到陣列(Iterator 不支援直接排序)
$files = iterator_to_array($filter);
usort($files, fn($a, $b) => $b->getMTime() <=> $a->getMTime());
foreach ($files as $file) {
echo $file->getPathname() . " | " . $file->getSize() . " bytes | " . date('Y-m-d H:i', $file->getMTime()) . "\n";
}
SplFileInfo 常用方法
| 方法 | 說明 |
getPathname() | 完整路徑 |
getFilename() | 檔名 |
getBasename($suffix) | 檔名(可移除副檔名) |
getExtension() | 副檔名 |
getSize() | 大小(bytes) |
getMTime() | 修改時間戳 |
getCTime() | inode 變更時間戳 |
getATime() | 最後存取時間戳 |
getPerms() | 權限(八進位) |
isDir()/isFile()/isLink() | 型別判斷 |
isReadable()/isWritable()/isExecutable() | 權限檢查 |
openFile($mode) | 返回 SplFileObject |
SplFileObject:檔案讀寫物件介面
<?php
// 逐行讀取大檔案(記憶體友善)
$file = new SplFileObject('large.log', 'r');
$file->setFlags(SplFileObject::READ_CSV); // CSV 模式
foreach ($file as $lineNum => $fields) {
// $fields 為陣列(CSV)或字串(一般模式)
if ($lineNum > 10000) break; // 限制讀取行數
}
// 寫入
$out = new SplFileObject('output.csv', 'w');
$out->fputcsv(['id', 'name', 'email']);
foreach ($users as $user) {
$out->fputcsv([$user->id, $user->name, $user->email]);
}
常見陷阱與最佳實踐
| 陷阱 | 後果 | 解決 |
| 相對路徑依賴 CWD | CLI/Web/Cron 執行目錄不同導致找不到檔 | 使用 __DIR__、realpath()、環境變數建立絕對路徑 |
未檢查 is_file() 直接讀取 | 目錄被當檔案讀取報警告 | 嚴格型別檢查 |
大檔案 file_get_contents() | 記憶體爆炸 | SplFileObject、fopen() 串流、分塊讀取 |
| 權限檢查 TOCTOU 競態 | is_writable() 後檔案權限被改 | 直接嘗試操作並捕獲異常(EAFP 原則) |
| Windows 路徑分隔符 | \ vs / 混用 | 統一用 DIRECTORY_SEPARATOR 或 /(PHP 內部支援) |
| 掃描超大目錄 | scandir() 記憶體峰值高 | 用 DirectoryIterator 逐個處理 |
總結
- 基礎函數:
scandir、pathinfo、filemtime、is_* 系列
- 遞迴處理:
RecursiveDirectoryIterator + RecursiveIteratorIterator
- 過濾排序:
FilterIterator、CallbackFilterIterator、RegexIterator + usort
- 大檔案讀寫:
SplFileObject 串流介面
- 路徑處理:
DIRECTORY_SEPARATOR、realpath()、pathinfo()
- 錯誤處理:
@ 抑制警告 + 異常捕獲、clearstatcache() 清除快取
掌握這些工具,能優雅地處理從簡單檔案列表到複雜目錄樹分析的各種需求。