PHP Rename File

Summary: in this tutorial, you will learn how to rename a file in PHP by using the rename() function.

Introduction to the PHP rename file function

To rename a file to the new one, you use the rename() function:

rename ( string $oldname , string $newname , resource $context = ? ) : bool
Code language: PHP (php)

The rename() function has three parameters:

  • $oldname is the name of the file that you want to rename.
  • $newname is the new name of the file.
  • $context is a valid context resource

The rename() function returns true if the $oldname file is renamed successfully or false otherwise.

If the $oldname file and $newname has a different directory, the rename() function will move the file from the current directory to the new one and rename the file.

Note that in case the $newname file already exists, the rename() function will overwrite it by the $oldname file.

PHP rename file examples

Let’s take some examples of renaming a file in PHP

1) Simple PHP rename file example

The following example uses the rename() function to rename the readme.txt file to readme_v2.txt file in the same directory:

<?php $oldname = 'readme.txt'; $newname = 'readme_v2.txt'; if (rename($oldname, $newname)) { $message = sprintf( 'The file %s was renamed to %s successfully!', $oldname, $newname ); } else { $message = sprintf( 'There was an error renaming file %s', $oldname ); } echo $message;
Code language: HTML, XML (xml)

2) Rename and move the file

The following example uses the rename() function to move the readme.txt to the public directory and rename it to readme_v3.txt:

<?php $oldname = 'readme.txt'; $newname = 'public/readme_v3.txt'; if (rename($oldname, $newname)) { $message = sprintf( 'The file %s was renamed to %s successfully!', $oldname, $newname ); } else { $message = sprintf( 'There was an error renaming file %s', $oldname ); } echo $message;
Code language: HTML, XML (xml)

3) PHP rename multiple files helper function

The following example defines a function that allows you to rename multiple files. The rename_files() function renames the files that match a pattern. It replaces a substring in the filenames with a new string.

<?php function rename_files(string $pattern, string $search, string $replace) : array { $paths = glob($pattern); $results = []; foreach ($paths as $path) { // check if the pathname is a file if (!is_file($path)) { $results[$path] = false; continue; } // get the dir and filename $dirname = dirname($path); $filename = basename($path); // replace $search by $replace in the filename $new_path = $dirname . '/' . str_replace($search, $replace, $filename); // check if the new file exists if (file_exists($new_path)) { $results[$path] = false; continue; } // rename the file $results[$path] = rename($path, $new_path); } return $results; }
Code language: HTML, XML (xml)

How it works.

  • First, get the paths that match a pattern by using the glob() function. The glob() function returns an array of files (or directories) that match a pattern.
  • Second, for each path, check if it is a file before renaming.

The following uses the replace_files() function to rename all the *.md files in the pages directory to the *.html files:

<?php rename_files('pages/*.md', '.md', '.html');
Code language: HTML, XML (xml)

Summary

  • Use the PHP rename() file function to rename a file.
Did you find this tutorial useful?