rename() renames or moves a filesystem entry, subject to filesystem support. This guide explains the function with focused examples and the decisions that matter in real applications.
What Is rename() in PHP?
Renames or moves a filesystem entry, subject to filesystem support.
A typical call looks like this:
<?php
rename($from, $to, [$context]);
The input arguments shown in the call identify the relevant connection, resource, value, path or configuration for the operation. Pay attention to argument order and to the return value demonstrated below.
Example 1: Basic Usage
This first example uses rename() directly to demonstrate its basic purpose.
<?php
$source = sys_get_temp_dir() . "/old-name.txt"; $target = sys_get_temp_dir() . "/new-name.txt"; file_put_contents($source, "Example"); var_dump(rename($source, $target)); unlink($target);
The returned value illustrates renames or moves a filesystem entry, subject to filesystem support. A move across filesystems may not be atomic; verify permissions and destination.
Example 2: A Different Input or Option
The next example changes the input or option, showing another supported use of rename().
<?php
$source = tempnam(sys_get_temp_dir(), "rename-"); $target = $source . ".txt"; var_dump(rename($source, $target)); unlink($target);
The returned value illustrates renames or moves a filesystem entry, subject to filesystem support. A move across filesystems may not be atomic; verify permissions and destination.
Practical Example: Applying the Function
In application code, rename() belongs in a controlled workflow with input validation, a checked result and cleanup where needed.
<?php
$oldPath = tempnam(sys_get_temp_dir(), "report-"); $newPath = $oldPath . ".done"; if (!rename($oldPath, $newPath)) throw new RuntimeException("Rename failed"); unlink($newPath);
The returned value illustrates renames or moves a filesystem entry, subject to filesystem support. A move across filesystems may not be atomic; verify permissions and destination.
Important Behavior and Edge Cases
- Main behavior: Renames or moves a filesystem entry, subject to filesystem support.
- Important limitation: A move across filesystems may not be atomic; verify permissions and destination.
- Requirements: Check the runtime, file permissions and operating system when results depend on the environment.
Comparison With Related Functions
| Function or Approach | When to Use It |
|---|---|
rename() | Renames or moves a filesystem entry, subject to filesystem support. |
copy | Copies file content to another path; rename() moves or changes a filesystem entry name. |
Common Beginner Mistakes
| Mistake | Correct Approach |
|---|---|
Ignoring the specific limits or preconditions of rename(). | A move across filesystems may not be atomic; verify permissions and destination. |
| Assuming every environment produces the same result. | Check the runtime, file permissions and operating system when results depend on the environment. |
Key Takeaways
- Renames or moves a filesystem entry, subject to filesystem support.
- A move across filesystems may not be atomic; verify permissions and destination.
- Check the runtime, file permissions and operating system when results depend on the environment.
Use rename() when its behavior matches your task, and verify the relevant return value before taking further action. Run examples that affect processes, users, privileges or the filesystem only in a controlled development environment.