PHP rename() 函数

定义和用法

rename() 函数用于重命名文件或目录，也可以移动文件到新位置。这个函数既可以改变文件名，也可以改变文件的位置，或者同时改变两者。

当目标文件已存在时，如果权限允许，rename() 会覆盖目标文件。在Windows系统中，如果目标文件已存在且没有被占用，操作会成功；在Unix/Linux系统中，如果目标文件已存在，它会被替换。

语法

rename ( string $oldname , string $newname [, resource $context ] ) : bool

参数说明：

• $oldname：原始文件或目录的路径（必需）
• $newname：新的文件或目录路径（必需）
• $context：上下文资源（可选，通常用于流操作）

参数详解

返回值

• 成功时：返回 true
• 失败时：返回 false，通常是由于以下原因：
  • 原始文件不存在
  • 权限不足
  • 目标目录不存在
  • 文件正在被使用（Windows系统）
  • 跨设备移动文件时遇到限制

示例

示例 1：基本重命名

重命名一个文件：

<?php
$oldname = 'old_file.txt';
$newname = 'new_file.txt';

if (rename($oldname, $newname)) {
    echo "文件重命名成功！";
} else {
    echo "文件重命名失败。";
}
?>

示例 2：移动文件到新目录

将文件移动到不同的目录：

<?php
$oldname = 'uploads/temp.jpg';
$newname = 'images/profile.jpg';

// 确保目标目录存在
if (!file_exists('images')) {
    mkdir('images', 0755, true);
}

if (rename($oldname, $newname)) {
    echo "文件移动成功！";
} else {
    echo "文件移动失败。";

    // 获取更多错误信息
    $error = error_get_last();
    if ($error) {
        echo " 错误信息: " . $error['message'];
    }
}
?>

示例 3：重命名目录

重命名一个目录：

<?php
$olddir = 'temp_data';
$newdir = 'archived_data';

if (is_dir($olddir)) {
    if (rename($olddir, $newdir)) {
        echo "目录重命名成功！";
    } else {
        echo "目录重命名失败。";
    }
} else {
    echo "源目录不存在。";
}
?>

示例 4：批量重命名文件

批量重命名一个目录中的所有文件：

<?php
$directory = 'photos';
$prefix = 'vacation_';
$counter = 1;

if (is_dir($directory)) {
    $files = scandir($directory);

    foreach ($files as $file) {
        if ($file === '.' || $file === '..') continue;

        $oldpath = $directory . '/' . $file;
        $extension = pathinfo($file, PATHINFO_EXTENSION);
        $newpath = $directory . '/' . $prefix . $counter . '.' . $extension;

        if (rename($oldpath, $newpath)) {
            echo "重命名 {$file} 为 {$prefix}{$counter}.{$extension}<br>";
            $counter++;
        } else {
            echo "重命名 {$file} 失败<br>";
        }
    }
}
?>

示例 5：使用上下文

使用上下文资源进行重命名操作：

<?php
// 创建上下文（虽然rename()通常不需要特殊的上下文）
$context = stream_context_create([
    'http' => [
        'method' => 'GET',
        'header' => "User-Agent: PHP\r\n"
    ]
]);

$oldname = 'data.txt';
$newname = 'backup_data.txt';

if (rename($oldname, $newname, $context)) {
    echo "使用上下文重命名成功！";
} else {
    echo "重命名失败。";
}
?>

注意事项和最佳实践

安全注意事项

跨平台兼容性

<?php
function safe_rename($oldname, $newname) {
    // 验证文件存在
    if (!file_exists($oldname)) {
        return ['success' => false, 'error' => '源文件不存在'];
    }

    // 确保目标目录存在
    $target_dir = dirname($newname);
    if (!is_dir($target_dir)) {
        if (!mkdir($target_dir, 0755, true)) {
            return ['success' => false, 'error' => '无法创建目标目录'];
        }
    }

    // 尝试重命名
    if (rename($oldname, $newname)) {
        return ['success' => true, 'error' => null];
    } else {
        $error = error_get_last();
        return ['success' => false, 'error' => $error['message'] ?? '未知错误'];
    }
}

// 使用安全的重命名函数
$result = safe_rename('source.txt', 'backup/source.txt');
if ($result['success']) {
    echo "操作成功！";
} else {
    echo "操作失败: " . $result['error'];
}
?>

常见问题解答

相关函数