PHP 文件管理系統核心類庫深度解析：IO 操作、遞歸處理與數據完整性

類設計哲學：封裝系統調用，統一錯誤處理

IO 類繼承自基類 SnkClass，核心職責是將底層文件系統操作（讀寫、複製、移動、刪除、搜尋、屬性獲取）封裝為統一、可復用、帶錯誤碼回饋的介面。關鍵屬性：

• $result：操作結果數組，成功時攜帶數據
• $buffer_size：讀寫緩衝區大小（默認 8KB），平衡內存與 I/O 次數
• $exist_dir：複製/移動目錄時記錄目標路徑中已存在的最深層級，解決「目標為源子目錄」的遞歸死循環問題

核心方法逐項拆解

1. 目錄列舉 list_dir()

返回結構化數組：[['name'=>..., 'location'=>絕對路徑, 'type'=>0目錄/1文件/-1其他], ...]。關鍵細節：

• 使用 realpath() 規範化路徑，補齊目錄分隔符
• !== FALSE 嚴格判斷 readdir() 返回值，避免文件名為 0 時誤判
• 忽略 . 和 .. 特殊項目
• 調用 clearstatcache() 清除文件狀態緩存，確保後續操作獲取最新屬性

2. 文件/目錄詳情 file_info()

返回包含名稱、路徑、類型、大小、訪問/修改/狀態變更時間、可讀/可寫權限的關聯數組。同樣依賴 realpath() 和 clearstatcache()。

3. 遞歸搜尋 seek_file()

支援正則模式、類型過濾（文件/目錄/全部）、子目錄深度限制、結果數量上限。演算法亮點：

• 參數嚴格驗證，錯誤碼 0x000B
• 深度優先遞歸，子目錄搜尋結果用 array_merge() 合併
• 類型過濾邏輯：$seek_type + $item['type'] == 1 精妙實現「僅文件/僅目錄/全部」三態判斷
• 達到 $limit 立即 break 並 array_splice() 截斷，避免資源浪費

4. 遞歸刪除 delete()

文件直接 unlink()，目錄遞歸清空後 rmdir()。任一子項失敗即整體回滾返回 FALSE，保證原子性。

5. 路徑規範化 generate_path()

處理相對/絕對路徑、跨平台分隔符、.. 回溯、非法字符過濾。核心流程：

1. 統一分隔符為 DIRECTORY_SEPARATOR
2. 分離基礎路徑與相對部分
3. realpath() 解析基礎路徑（不存在則退回當前工作目錄）
4. 逐段處理相對部分：.. 彈棧、. 忽略、普通段入棧
5. 重組為標準絕對路徑

6. 多級目錄創建 make_dir()

基於 generate_path() 分解路徑層級，逐級 mkdir()。記錄 $exist_dir 供上層複製/移動操作判斷目標是否為源子目錄。

7. 文件完整性驗證 verify_file()

三層校驗：存在性 → 大小一致 →（可選）MD5 雜湊比對。超過 1GB 文件可跳過 MD5 以節省 CPU，僅比對大小。

8. 複製與移動 copy() / move()

共用遞歸框架，差異在於移動最後需刪除源文件/目錄。關鍵機制：

• 隱藏參數 $sub 區分外部調用（FALSE，重置 $exist_dir）與內部遞歸（TRUE，保持 $exist_dir）
• 目標為源子目錄時，$src == $this->exist_dir 觸發提前返回，打破遞歸循環
• 複製文件後強制 verify_file()，失敗則刪除目標文件並報錯
• 移動文件驗證通過後 unlink($src)，目錄遞歸完成後 rmdir($src)（非共用父目錄情況）

9. 移除 C 風格註釋 no_comment()

有限狀態機（FSM）逐字符解析，狀態包括：雙引號字符串、單引號字符串、行註釋（//）、塊註釋（/* */）、轉義字符。流程：

1. 以緩衝區分塊讀取源文件，寫入臨時文件
2. 逐字符狀態遷移，註釋狀態下跳過輸出
3. 臨時文件寫滿或讀取完畢時刷入源文件
4. 最後回寫源文件，清除行尾空白，保持原換行符風格
5. 全程 flock(LOCK_EX) 獨佔鎖，防止併發損壞

錯誤碼體系：標準化異常回饋

十六進制錯誤碼（0x0001~0x000D）覆蓋目錄/文件不存在、權限不足、參數錯誤、磁盤空間不足、鎖定失敗等場景，統一由基類 error_occur() 處理，便於上層統一捕獲、記錄、轉換為用戶友好提示。

工程化啟示與現代化改造建議

適用場景與替代方案

• 適用：自建 CMS/網盤/部署工具的核心文件操作層、教學理解遞歸文件系統算法、需精細控制錯誤碼的舊系統維護。
• 替代：現代項目優先考慮 Flysystem（統一本地/雲存儲介面）、Symfony Filesystem（聲明式操作）、Laravel Storage 外觀、原生 RecursiveDirectoryIterator + RecursiveIteratorIterator 替代手寫遞歸。

這個 IO 類展示了 PHP 早期面向對象封裝系統調用的經典模式：狀態機解析、遞歸目錄樹、錯誤碼體系、併發鎖保護。雖然現代生態提供了更優雅的抽象，但其核心算法思維（路徑規範化、遞歸終止條件、原子性操作、資源清理）仍是每位 PHP 開發者必備的內功。

1. 上一篇文章： PHP 實現站內全文搜尋：從遞歸遍歷到高效索引的進化之路
2. 下一篇文章： PHP 啟用 OpenSSL 擴展完整指南：Windows 與 Linux 環境差異化配置

PHP 相關知識

排名前十的 PHP 調試工具深度評測（上）

前言 PHP 擁有豐富的工具生態，優秀的調試工具能大幅提升開

PHP Imagick 圖像處理全能類：裁切、縮略圖、水印、GIF 動圖完美支援實戰詳解

PHP Imagick 圖像處理全能類：裁切、縮略圖、水印、

PHP + MySQL + Highcharts 實作互動式圓餅圖完整教學

專案概覽 本教學示範如何結合 PHP 後端、MySQL 資料

PHP ZipArchive 壓縮打包與下載完整實作：目錄遍歷、多檔打包、串流輸出

前言：打包下載是後台管理的高頻需求 用戶勾選多個檔案 → 伺