PHP rename() 完全指南：重命名、移動、跨分區、刪除替代技巧與避坑

rename() 是 PHP 檔案系統操作的核心函數，**同時具備重命名、移動檔案/目錄**功能。本文詳細說明語法、跨分區限制、封裝協定一致性、Windows/Linux 差異、資源串流上下文、以及**巧用 rename 實現刪除**等進階技巧與避坑指南。

一、語法與參數

rename(string $from, string $to, ?resource $context = null): bool

• $from：現有檔案/目錄路徑。
• $to：新路徑（**父目錄必須存在**）。
• $context：串流上下文（如 FTP/SSH2 封裝協定需認證時）。
• 成功回傳 true，失敗 false 並觸發 E_WARNING。

二、核心行為對照表

三、基本範例

<?php
// 重命名檔案
rename('images', 'pictures'); // 目錄重命名

// 移動檔案到子目錄 (需確保 uploads 存在)
rename('tmp/upload_123.jpg', 'uploads/2024/01/photo.jpg');

// 跨分區移動大檔案：建議改用 copy+unlink 可控錯誤處理
if (@rename($src, $dst)) {
    echo '移動成功';
} else {
    // 降級策略
    if (copy($src, $dst)) { unlink($src); echo '複製移動成功'; }
    else { echo '移動失敗'; }
}

四、封裝協定一致性要求

$from 與 $to **必須使用相同封裝協定**，否則失敗：

• rename('file.txt', 'ftp://user:pass@host/file.txt') ❌
• rename('ftp://user:pass@host/old.txt', 'ftp://user:pass@host/new.txt') ✅
• rename('/local/path', '/other/local/path') ✅

五、進階技巧：巧用 rename 實現「安全刪除」

Windows PHP 早期版本 unlink() 可能受限，可將檔案移至系統暫存目錄由 OS 清理：

$tmp = sys_get_temp_dir() . '/php_delete_' . uniqid();
rename($targetFile, $tmp); // 移至暫存區
// 註冊 shutdown function 或 cron 定期清理 $tmp 目錄

六、串流上下文應用：FTP/SSH2 遠端重命名

$ctx = stream_context_create([
    'ftp' => ['username'=>'user', 'password'=>'pass', 'overwrite'=>true]
]);
rename('ftp://server/path/old.txt', 'ftp://server/path/new.txt', $ctx);

七、常見錯誤代碼與排查

八、最佳實務清單

1. 操作前用 clearstatcache() 清除快取，確保 file_exists()/is_writable() 即時性。
2. 跨分區大檔案：**改用 copy() + unlink()**，可加入進度回呼、斷點續傳邏輯。
3. Windows 覆蓋失敗：**先 @unlink($to) 再 rename()**。
4. 目錄移動前確認無符號連結循環（is_link() 檢查）。
5. 記錄操作日誌（來源、目標、時間、結果），利稽核追蹤。

掌握 rename() 完整行為邊界，能在檔案上傳整理、部署發佈、日誌輪轉、暫存清理等場景寫出**健壯、跨平台、高效能**的檔案系統代碼。