PHP rename 函数
最后修改于 2025 年 4 月 3 日
PHP 的 rename 函数用于重命名文件或目录。如果路径在同一文件系统上，它还可以将文件在目录之间移动。
基本定义
rename 函数更改文件/目录的名称或位置。成功时返回 true，失败时返回 false。
语法：rename(string $oldname, string $newname, resource $context = null): bool。两个参数都必须是表示有效路径的字符串。
基本文件重命名示例
这展示了 rename 最简单的文件重命名用法。
basic_rename.php
<?php
declare(strict_types=1);
$oldname = 'oldfile.txt';
$newname = 'newfile.txt';
if (rename($oldname, $newname)) {
echo "File renamed successfully";
} else {
echo "Error renaming file";
}
这会将同一目录下的 'oldfile.txt' 重命名为 'newfile.txt'。成功时函数返回 true。始终检查返回值以处理错误。
在目录之间移动文件
rename 可以在同一文件系统上的目录之间移动文件。
move_file.php
<?php
declare(strict_types=1);
$source = 'documents/report.txt';
$destination = 'archives/report_2023.txt';
if (rename($source, $destination)) {
echo "File moved and renamed successfully";
} else {
echo "Error moving file";
}
这会将 report.txt 从 documents 移动到 archives，同时重命名它。两个操作都是原子性的。目录必须事先存在。
目录重命名示例
rename 与目录的处理方式与文件相同。
rename_dir.php
<?php
declare(strict_types=1);
$olddir = 'temp';
$newdir = 'temporary_files';
if (rename($olddir, $newdir)) {
echo "Directory renamed successfully";
} else {
echo "Error renaming directory";
}
这会将 'temp' 目录重命名为 'temporary_files'。如果目标目录已存在或权限不足，操作将失败。
错误处理示例
在进行文件系统操作时，正确的错误处理至关重要。
error_handling.php
<?php
declare(strict_types=1);
$old = 'nonexistent.txt';
$new = 'newfile.txt';
if (!file_exists($old)) {
die("Source file doesn't exist");
}
if (file_exists($new)) {
die("Target file already exists");
}
if (!rename($old, $new)) {
die("Error: " . error_get_last()['message']);
}
echo "File renamed successfully";
这会在尝试重命名之前检查常见的错误情况。如果操作失败，它还会提供详细的错误消息。
跨设备重命名示例
在跨文件系统移动时，rename 可能会失败，需要使用 copy。
cross_device.php
<?php
declare(strict_types=1);
function moveFile(string $source, string $dest): bool {
if (rename($source, $dest)) {
return true;
}
if (!copy($source, $dest)) {
return false;
}
unlink($source);
return true;
}
$result = moveFile('/mnt/volume1/file.txt', '/mnt/volume2/file.txt');
echo $result ? "Success" : "Failed";
这会首先尝试直接重命名，然后回退到 copy+delete。该函数会处理源和目标位于不同设备的情况。
最佳实践
- 检查权限：提前验证读/写权限。
- 验证路径：确保路径有效且可访问。
- 处理错误：实现正确的错误处理逻辑。
- 原子操作：使用 rename 进行原子文件更新。
- 备份：关键操作考虑进行备份。
来源
本教程介绍了 PHP 的 rename 函数，并通过实际示例展示了文件和目录的重命名和移动操作。
作者
列出 所有 PHP 文件系统函数。