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 = ? ) : boolCode 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.