PHP: rename - Manual

Description

bool rename ( string oldname, string newname [, resource context] )

Attempts to rename oldname to newname.

Returns TRUE on success or FALSE on failure.

Example 1. Example with rename()

<?php rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt"); ?>

Note: Prior to PHP 4.3.3, rename() could not rename files across partitions on *nix based systems.

Note: As of PHP 5.0.0 rename() can also be used with some URL wrappers. Refer to Appendix L for a listing of which wrappers support rename().

Note: The wrapper used in oldname MUST match the wrapper used in newname.

Note: Context support was added with PHP 5.0.0. For a description of contexts, refer to Reference CXXII, Stream Functions.

User Contributed Notes
rename

sophie at sitadelle dot com
14-Nov-2003 10:22


Hello!

For unix/linux users: it is usefull to know that if you use rename() for a directory, the new one will be created with the current umask!

JulienC at Psychologie-fr dot com
13-Mar-2002 10:46


Be carefull if you code for different OS. *nix versions will overwrite the destination file if it exists, but on windows it wont ! You will instead get a nice: "Warning: Rename failed (File exists) in...". So dont forget to unlink :)



/jc

blujay
08-Feb-2002 03:32


You can always chdir() to the parent directory of what you're renaming, and rename the directory or file directly.  For example:



$oldWD = getcwd();

chdir($dirWhereRenameeIs);

rename($oldFilename, $newFilename);

chdir($oldWD);

pearcec at commnav dot com
15-Jun-2001 03:17


If you rename one directory to another where the second directory exists as an empty directory it will not complain.





Not what I expected.





[pearcec@abe tmp]$ mkdir test1


[pearcec@abe tmp]$ mkdir test2


[pearcec@abe tmp]$ touch test1/test


[pearcec@abe tmp]$ php


<?php


rename("test1","test2");


?>


X-Powered-By: PHP/4.0.5


Content-type: text/html





[pearcec@abe tmp]$ ls -al


total 12


drwxr-xr-x    3 pearcec  commnav      4096 Jun 15 13:17 .


drwxr-xr-x   18 pearcec  commnav      4096 Jun 15 13:15 ..


drwxr-xr-x    2 pearcec  commnav      4096 Jun 15 13:16 test2


[pearcec@abe tmp]$ ls -la test2/


total 8


drwxr-xr-x    2 pearcec  commnav      4096 Jun 15 13:16 .


drwxr-xr-x    3 pearcec  commnav      4096 Jun 15 13:17 ..


-rw-r--r--    1 pearcec  commnav         0 Jun 15 13:16 test


[pearcec@abe tmp]$

michael-nospam at sal dot mik dot hyperlink dot net dot au
25-Nov-1999 01:43


Note, that on Unix, a rename is a beautiful way of getting atomic updates to files.





Just copy the old contents (if necessary), and write the new contents into a new file, then rename over the original file.





Any processes reading from the file will continue to do so, any processes trying to open the file while you're writing to it will get the old file (because you'll be writing to a temp file), and there is no "intermediate" time between there being a file, and there not being a file (or there being half a file).





Oh, and this only works if you have the temp file and the destination file on the same filesystem (eg. partition/hard-disk).