PHP rename( ) Function

The rename() function in PHP is an inbuilt function that is used to rename a file or directory. It attempts to change an old name of a file or directory with a new name specified by the user and it may move between directories if necessary. If the new name specified by the user already exists, the rename() function overwrites it. The old name of the file and the new name specified by the user are sent as parameters to the rename() function and it returns a True on success and a False on failure.

Syntax:

rename(oldname, newname, context)

Parameters:

The rename() function in PHP accepts three parameters.

1. oldname: It is a mandatory parameter that specifies the old name of the file or directory.
2. newname: It is a mandatory parameter that specifies the new name of the file or directory.
3. context: It is an optional parameter that specifies the behavior of the stream .

Return Value:

• It returns a True on success and a False on failure.

Errors And Exception

1. The rename() function generates a Warning if the newname already exists while renaming a directory.
2. The wrapper used in oldname must match the wrapper used in newname.
3. If the destination filesystem doesn't permit chown() or chmod() system calls to be made on files, then rename() function may generate Warnings.

Examples:

Input : $old_name = "gfg.txt" ; 
        $new_name = "newgfg.txt" ; 
        rename( $new_name, $old_name) ;

Output : 1

Input : $old_name = "gfg.txt" ;
        $new_name = "newgfg.txt" ; 
        if(file_exists($new_name))
        { 
           echo "Error While Renaming $old_name" ;
        }
        else
        {
           if(rename( $old_name, $new_name))
           { 
           echo "Successfully Renamed $old_name to $new_name" ;
           }
          else
          {
           echo "A File With The Same Name Already Exists" ;
          }
        }

Output : Successfully Renamed gfg.txt to newgfg.txt

Example of rename() Function

Below programs illustrate the rename() function. Suppose there is a file named "gfg.txt"

Example 1: Thisexample shows the basic usage of the rename() function. It attempts to rename a file named gfg.txt to newgfg.txt. If successful, it returns 1 (True), otherwise, it returns 0 (False).

<?php 
// Old Name Of The file
$old_name = "gfg.txt" ; 

// New Name For The File
$new_name = "newgfg.txt" ; 

// using rename() function to rename the file
rename( $old_name, $new_name) ;

?>

Output:

1

Example 2: In this example, we check if a file with the new name already exists. If it does, an error message is displayed. If not, the program attempts to rename the file and displays a success or failure message based on the outcome.

<?php 
// Old Name Of The file
$old_name = "gfg.txt" ; 
 
// New Name For The File
$new_name = "newgfg.txt" ; 
 
// Checking If File Already Exists
if(file_exists($new_name))
 { 
   echo "Error While Renaming $old_name" ;
 }
else
 {
   if(rename( $old_name, $new_name))
     { 
        echo "Successfully Renamed $old_name to $new_name" ;
     }
     else
     {
        echo "A File With The Same Name Already Exists" ;
     }
  }
?>

Output:

Successfully Renamed gfg.txt to newgfg.txt

Related Articles:

• PHP | copy( ) Function
• PHP | unlink() function