rename(string $from, string $to, ?resource $context = null): bool
嘗試將檔案或目錄從 $from 移動/重命名為 $to。成功返回 true,失敗返回 false 並觸發 E_WARNING。
<?php
$old = '/var/www/uploads/temp_123.jpg';
$new = '/var/www/uploads/user_456.jpg';
if (file_exists($old)) {
if (rename($old, $new)) {
echo "重命名成功: $new";
} else {
echo "重命名失敗 (權限/跨分區/目標存在)";
}
} else {
echo "來源檔案不存在: $old";
}
| 情況 | 行為 | 解決方案 |
|---|---|---|
| 跨檔案系統/分區 | 失敗 (EXDEV) | 用 copy() + unlink() 替代 |
| 目標已存在 | 覆蓋 (Windows) / 失敗 (Linux, 除非目標是目錄且為空) | 先 unlink($new) 或檢查 file_exists |
| 目錄非空重命名 | Linux 允許 (同分區)、Windows 失敗 | 遞迴移動或用 rename 父目錄 |
| 權限不足 | 失敗 (EACCES) | 確保 PHP 進程用戶對來源/目標目錄有寫入權限 |
| 開啟中的檔案 | Windows 鎖定失敗、Linux 允許 (inode 不變) | 關閉句柄後再改名 |
function safeRename(string $src, string $dst): bool {
if (@rename($src, $dst)) return true; // 同分區快速成功
// 跨分區:複製 + 刪除
if (!copy($src, $dst)) return false;
// 驗證大小一致
if (filesize($src) !== filesize($dst)) {
unlink($dst);
return false;
}
return unlink($src);
}
<?php
$dir = '/var/www/images';
$prefix = 'img_';
$i = 1;
foreach (new DirectoryIterator($dir) as $file) {
if ($file->isDot() || !$file->isFile()) continue;
$ext = $file->getExtension();
$newName = sprintf('%s%04d.%s', $prefix, $i++, $ext);
rename($file->getPathname(), $dir . '/' . $newName);
}
echo "完成重命名 $i 個檔案";
$tmp = $target . '.tmp.' . random_int(1000, 9999);
file_put_contents($tmp, $data);
rename($tmp, $target); // 同分區下原子性替換