PHP rename() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Filesystem

Definition

In PHP, rename() renames a file or folder. It can also move it to a different folder if the new path points somewhere else.

You pass the old name and the new name. PHP changes the name on disk and returns true or false. The content of the file stays the same.

Syntax

Call rename() with the values you need. Start with this line.

PHP
$ok = rename('old.txt', 'new.txt');
CallWhat it does
rename('old.txt', 'new.txt')Renames old.txt to new.txt in the same folder.
rename('a.txt', 'archive/a.txt')Moves a.txt into the archive folder, if that folder exists.
rename('images', 'photos')Renames a folder.

rename() works on files and folders. If the target file already exists, rename() usually replaces it without asking on Linux and macOS. On Windows the behaviour can differ when the target already exists.

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

Parameters

ParameterDescription
fromRequired. The current path of the file or folder.
toRequired. The new path. If it is in another folder, the item is moved there.
contextOptional. A stream context created with stream_context_create(). Most scripts leave it out.

Return Value

Return ValueDescription
boolReturns true on success or false on failure.

PHP Examples

Example 1 — Rename a File

Create a file called old.txt and rename it to new.txt.

PHP
<?php
$dir = sys_get_temp_dir();
file_put_contents($dir . '/old.txt', 'Hello');

if (rename($dir . '/old.txt', $dir . '/new.txt')) {
    echo 'Renamed', PHP_EOL;
}

echo 'old.txt exists: ', file_exists($dir . '/old.txt') ? 'yes' : 'no', PHP_EOL;
echo 'new.txt exists: ', file_exists($dir . '/new.txt') ? 'yes' : 'no', PHP_EOL;

unlink($dir . '/new.txt');

How It Works

  1. file_put_contents() creates old. txt with the text Hello.
  2. rename() changes the name from old. txt to new.txt and returns true.
  3. file_exists() shows that the old name is gone and the new name is there.
  4. unlink() deletes the test file at the end.

Example 2 — Rename a File That Does Not Exist

rename() returns false and shows a warning when the source is missing, so check it first.

PHP
<?php
$from = sys_get_temp_dir() . '/missing_source.txt';
$to   = sys_get_temp_dir() . '/target.txt';

if (!file_exists($from)) {
    echo 'Source does not exist', PHP_EOL;
} elseif (rename($from, $to)) {
    echo 'Renamed', PHP_EOL;
} else {
    echo 'Rename failed', PHP_EOL;
}

How It Works

  1. The file missing_source. txt was never created.
  2. file_exists() returns false, so the first branch runs.
  3. rename() is never called, so PHP shows no warning.
  4. A clear message is printed instead.

Example 3 — Rename Over an Existing File

See what happens when the new name is already taken.

PHP
<?php
$dir = sys_get_temp_dir();
file_put_contents($dir . '/a.txt', 'first');
file_put_contents($dir . '/b.txt', 'second');

rename($dir . '/a.txt', $dir . '/b.txt');

echo file_get_contents($dir . '/b.txt'), PHP_EOL;
echo 'a.txt exists: ', file_exists($dir . '/a.txt') ? 'yes' : 'no', PHP_EOL;

unlink($dir . '/b.txt');

How It Works

  1. Two files are created with different content.
  2. rename() moves a. txt onto b.txt, and the old b.txt is replaced.
  3. Reading b. txt now shows the text from a.txt, which is first.
  4. a. txt no longer exists because it was renamed. Always check file_exists() when you cannot afford to lose a file.

Frequently Asked Questions

It renames a file or folder, or moves it to a new path. The function returns true on success and false on failure.
Yes. Give a new path in another folder, such as rename('a.txt', 'archive/a.txt'). The target folder must already exist.
On Linux and macOS it usually replaces the target file. Check with file_exists() first if you need to keep the old file.
The source may not exist, the target folder may be missing, you may lack permission, or you may be moving across different disks or drives.
rename() changes the name or location, so there is still just one file. copy() makes a second file and leaves the original in place.

Next: rewind()

rewind() moves the file pointer back to the very beginning of an open file or stream.

rewind() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful