How to Rename or Move Files in PHP with rename()

In PHP, managing files on your server is a fundamental task, and the built-in rename() function is the primary tool for both renaming and moving files across directories. This article provides a concise, step-by-step guide on how to use the rename() function, complete with code examples for both renaming and moving files, as well as essential tips for handling common errors.

Understanding the rename() Syntax

The rename() function takes two main arguments: the current path of the file and the desired new path.

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

$from: The path to the original file.
$to: The destination path (which can include a new filename, a new directory, or both).
Return Value: Returns true on success, or false on failure.

How to Rename a File

To rename a file within the same directory, keep the directory path the same in both arguments and only change the filename.

$oldName = "documents/report_draft.txt";
$newName = "documents/final_report.txt";

if (rename($oldName, $newName)) {
    echo "File renamed successfully.";
} else {
    echo "Error: Unable to rename file.";
}

How to Move a File

To move a file to a different directory, change the directory path in the second argument. You can keep the original filename or change it during the move.

$source = "uploads/photo.jpg";
$destination = "images/vacation.jpg";

if (rename($source, $destination)) {
    echo "File moved successfully.";
} else {
    echo "Error: Unable to move file.";
}

Important Considerations and Best Practices

Before executing the rename() function, keep the following rules in mind to avoid runtime errors:

Check Directory Existence: The destination directory must already exist. PHP will not automatically create new folders. You can use mkdir() to create a directory if it does not exist.
File Permissions: The PHP process must have write permissions for both the source file and the destination directory.
Overwriting Files: If a file already exists at the destination path, PHP will overwrite it without warning. Use file_exists() beforehand if you want to prevent overwriting.
Cross-Volume Restrictions: Moving files between different partitions or mounts (e.g., from a temporary directory to a network drive) might fail on certain operating systems. In those cases, you may need to copy the file using copy() and then delete the original using unlink().