PHP Filesystem rename() Function

---

---

The PHP Filesystem rename() function is used to rename a file or directory, and this function can return true on success, or false on failure.

This function can attempt to rename oldname to newname, moving it between directories if necessary. If renaming a file and newname exists, it can be overwritten. If renaming a directory and newname exists, this function can emit a warning.

Syntax

Below is the syntax of the PHP Filesystem rename() function −

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

Parameters

Below are the required and optional parameters of the rename() function −

Return Value

The function rename() returns TRUE on success, and FALSE on failure.

PHP Version

The rename() function was first introduced as part of core PHP 4 and work well with the PHP 5, PHP 7 and PHP 8.

Example

Here is the basic example to see how the PHP Filesystem rename() function is used to change the name of the file given.

<?php
   rename("/PhpProject/sample.txt", "/PhpProject/php/sample1.txt");
   echo "The File is Renamed Successfully.";
?>

Output

Here is the outcome of the following code −

The File is Renamed Successfully.

Example

Here is the another example to show the usage of rename() function to change the file name to new name while handling error.

<?php
   $old_file = 'oldfile.txt';
   $new_file = 'newfile.txt';

   if (rename($old_file, $new_file)) {
      echo "File renamed successfully.";
   } else {
      echo "Error renaming file.";
   }

Output

This will produce the following result −

File renamed successfully.

Example

Here is one more example to show the usage of the rename() function by renaming the name of the directory.

<?php
   //Create a new directory inside the current directory
   mkdir("PhpProject");

   $oldname = 'PhpProject';
   $newname = 'MyPhpProjects';

   //Rename the directory
   $success = rename($oldname, $newname);

   if($success) {
      echo "$oldname is renamed to $newname.\n";
   } else {
      echo "$oldname can not be renamed to $newname.\n";
   }
?> 

Output

This will generate the below output −

PhpProject is renamed to MyPhpProjects.

Example

Here is one more example to use rename() function for moving a file to a different directory by changing file's name.

<?php
// Current file path and name
$old_path = '/Users/Desktop/PHP/PhpProjects/myfile.txt';

// New directory path and new file name
$new_directory = '/Users/Desktop';
$new_filename = 'newfile.txt';

// Combine new directory path and new filename
$new_path = $new_directory. '/' . $new_filename;

// Attempt to rename (move) the file
if (rename($old_path, $new_path)) {
   echo "File moved successfully to $new_path.";
} else {
   echo "Error moving file.";
}
?> 

Output

This will lead to the following output −

File moved successfully to /Users/Desktop/newfile.txt

Important Notes

Here are some important point to keep in mind while working with rename() function −

• On Windows, if it exists, it must be readable. Otherwise, rename() fails and returns E_WARNING.
• The wrapper used in oldname must match the one used in newname.

Summary

The rename() method is a built-in function to change the name of the given file. It is very helpful for renaming the file and directory in PHP.