Delicious Bookmark this on Delicious Share on Facebook SlashdotSlashdot It! Digg! Digg



PHP : Function Reference : Filesystem Functions : rename

rename

Renames a file or directory (PHP 4, PHP 5, PECL zip:1.1.0-1.4.1)
bool rename ( string oldname, string newname [, resource context] )

Attempts to rename oldname to newname.

Parameters

oldname
Note:

The old name. The wrapper used in oldname must match the wrapper used in newname.

newname

The new name.

context
Note:

Context support was added with PHP 5.0.0. For a description of contexts, refer to Streams.

Return Values

Returns TRUE on success or FALSE on failure.

ChangeLog

Version Description
5.0.0 rename() can now also be used with some URL wrappers. Refer to Appendix O, List of Supported Protocols/Wrappers for a listing of which wrappers support rename().
4.3.3 rename() is now able to rename files across partitions on *nix based systems.

Examples

Example 669. Example with rename()

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


Related Examples ( Source code ) » rename




Code Examples / Notes » rename

blujay

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);


jeppe

Until recently you could end the dirname your wanted to rename to with a slash:
rename("mydir/my2nddir/","mydir/my3nddir/")
But now it doesn't work (php warns that it is unable to access mydir/my3nddir/).
So always leave out a final slash in your dirname:
rename("mydir/my2nddir","mydir/my3nddir")
The same goes for mkdir().


jrog

To anyone wondering, rename($old, $new) returns FALSE if $new already exists.  My script called for overwriting the file if it existed so I did this:
if(file_exists($new)) { unlink($new); }
$ok = rename($old, $new);
This did not work as expected.  If $new actually existed then it worked fine.  That is the file found at path $new was deleted and replaced with the file found at path $old.  However, if $new did NOT exist then the result was the file at  path $old vanished into oblivion.  After debugging a bit, it seems that rename() was getting executed before the if-statement.  So rename() moved $old to $new, THEN the if-statement evaluated to true and deleted the file I just moved.  Anyway, this fixed it:
if(file_exists($new)) {
unlink($new);
$ok = rename($old, $new);
} else { $ok = rename($old, $new); }
Very strange ... I hope this helps somebody


eric themepark.com

This was a fun one-- on Win XP, rename throws a "permission deined" if you try to rename across volumes.. i.e. rename("c:\windows\temp\x.txt", "g:\destination") will fail.

php

rename() fails with PHP4 and PHP5 under Windows if the destination file exists, regardless of file permission settings. I now use a function similar to that of ddoyle [at] canadalawbook [dot] ca, which first tries rename(), checks if it returned FALSE and then uses copy()/unlink() if it failed.
However, copy() is, unlike rename(), NOT useable for "atomic updates". Another process may actually access the destination file while copy() is working. In such a case, the other process with perceive the file as empty or with incomplete content ("half written").


ddoyle

rename() definitely does not follow the *nix rename convention on WinXP with PHP 5.  If the $newname exists, it will return FALSE and $oldname and $newname will remain in their original state.  You can do something like this instead:
function rename_win($oldfile,$newfile) {
  if (!rename($oldfile,$newfile)) {
     if (copy ($oldfile,$newfile)) {
        unlink($oldfile);
        return TRUE;
     }
     return FALSE;
  }
  return TRUE;
}


php

Remark for "php at stock-consulting dot com"'s note:
This depends on the operating system.
On windows-systems you can't rename a file to an existing destination (ok, with tools you can - but they unlink the exisiting one before).


squid

php5-5.1.6_3 from ports on FreeBSD 6.2-RELEASE  still throws warning when attemting to rename across partitions. It does rename fine though. Weird.

jmalinsky

On WinXP/PHP 5+, not only does rename()  not follow the *nix rename as noted below, but other things (do not) happen.  If you're trying to rename a directory, files within the directory will NOT be present in the renamed directory, though sub-directories WILL be present.  Ultra-strange.  And as noted, your 'old' directory will remain on the server totally intact, which can be very confusing.
To try and rename a folder on XP via PHP, I wound up using a workaround: first i used the copydirr() function posted by makarenkoa at ukrpost dot net on the "copy" page of the online manual to copy all folders and files within the original directory to the new one... and then to delete the original directory (and all files/folders beneath it), i used the delDir() function corrected by czambran at gmail dot com on the "rmdir" page of the online manual.  Why didn't I use unlink()?  Because, unlink does NOT work on Windows systems either (and even if it did work, its not recursive without extra coding).
So, all in all, rename() is pretty much a useless function if you are intending to rename a folder on an XP box.


michael-nospam

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).


php-public

It is unclear what encoding the arguments of rename should have; For PHP 4.3, on a HFS+ filesystems, rename() did not handle UTF-8 strings, and returned an error.

pearcec

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]$


tbrillon

I needed to move a file to another folder regardless if that file existed in the target already so I wrote a small piece to append a unique number to each file.
$rem = $_GET['file'];
$ticket = uniqid(rand(), true);
rename("$rem", "www/home/storefile/$ticket$rem");
the output looks like this - 6881432893ad4925a1.70147481filename.txt
This also helps if you want different versions of the file stored.


bobbfwed

I have programmed a really nice program that remotely lets you manage files as if you have direct access to them (http://sourceforge.net/projects/filemanage/). I have a bunch of really handy functions to do just about anything to files or directories. In it I just finished redevloping the directory move function to utilize PHP's rename() since it is way more efficient than a copy/delete process. It goes through (recursivly) and renames all the files to a new location instead of copying them. It recreates the directory structure in the new location. It also allows you to overwrite the existing files, or not.
Here is the function I made; it will likely need tweaking to work as a standalone script, since it relies of variables set by my program (eg: loc1 -- which dynamically changes in my program):
<?PHP
 // loc1 is the path on the computer to the base directory that may be moved
define('loc1', 'C:/Program Files/Apache Group/Apache/htdocs', true);
 // move a directory and all subdirectories and files (recursive)
 // void dirmv( str 'source directory', str 'destination directory' [, bool 'overwrite existing files' [, str 'location within the directory (for recurse)']] )
function dirmv($source, $dest, $overwrite = false, $funcloc = NULL){
 if(is_null($funcloc)){
   $dest .= '/' . strrev(substr(strrev($source), 0, strpos(strrev($source), '/')));
   $funcloc = '/';
 }
 if(!is_dir(loc1 . $dest . $funcloc))
   mkdir(loc1 . $dest . $funcloc); // make subdirectory before subdirectory is copied
 if($handle = opendir(loc1 . $source . $funcloc)){ // if the folder exploration is sucsessful, continue
   while(false !== ($file = readdir($handle))){ // as long as storing the next file to $file is successful, continue
     if($file != '.' && $file != '..'){
       $path  = $source . $funcloc . $file;
       $path2 = $dest . $funcloc . $file;
       if(is_file(loc1 . $path)){
         if(!is_file(loc1 . $path2)){
           if(!@rename(loc1 . $path, loc1 . $path2)){
             echo '<font color="red">File ('.$path.') could not be moved, likely a permissions problem.</font>';
           }
         } elseif($overwrite){
           if(!@unlink(loc1 . $path2)){
             echo 'Unable to overwrite file ("'.$path2.'"), likely to be a permissions problem.';
           } else
             if(!@rename(loc1 . $path, loc1 . $path2)){
               echo '<font color="red">File ('.$path.') could not be moved while overwritting, likely a permissions problem.</font>';
             }
         }
       } elseif(is_dir(loc1 . $path)){
         dirmv($source, $dest, $overwrite, $funcloc . $file . '/'); //recurse!
         rmdir(loc1 . $path);
       }
     }
   }
   closedir($handle);
 }
} // end of dirmv()
?>
This new function will be in 0.9.7 (the next release of File Manage) which should release sometime early February.
Hope this helps some people.


sophie

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!


kitty_zoso

Beware of rename if you're interested in preserving the case of filenames.  I'm writing a backup application using the command line version of php 5 on Windows XP and wanted to detect when the case of a source dir entry changed so I could rename it on the backup drive.
For instance, \common\kathy has been renamed to \common\Kathy on the source drive, so I wanted to rename the target directory, so a restore operation will have the new name to use.  The rename function didn't return false, but didn't change the case of the entry!  As a workaround (ugh) I change it to "something else" then do the final rename: instead of
rename('kathy','Kathy');
I use
rename('kathy', '~kathy~');
rename('~kathy~', 'Kathy');


david thole root

As of PHP 5.1.4 compiled on a mac, using rename with spaces one should just use the space.   Take for example:
rename("/tmp/somefile.tar", "/mnt/laptop storage/somefile.tar");
If you use the backslash, like if you were cd-ing to the directory, rename will fail.  Example:
rename("/tmp/somefile.tar", "/mnt/laptop\ storage/somefile.tar");
While not really a bug, it did confuse me for a little bit while working on a backup script.


php

As described from the unlink() page:
You have to release any handles to the file before you can rename it (True on Windows, at least).
This will NOT work, you'll receive permission denied errors:
<?php
   $fileHand = fopen('tempFile.txt', 'r');
   rename( 'tempFile.txt', 'tempFile2.txt' ); // Permission Denied!
?>
Simply close the handle to fix this:
<?php
   $fileHand = fopen('tempFile.txt', 'r');
   fclose($fileHand);
   rename( 'tempFile.txt', 'tempFile2.txt' );
?>
This has me scratching my head for some time, as the handle was opened at the top of a marge function, and the rename was at the bottom.


tomfelker

Actually, I'm pretty sure that rename follows the convention of *nix rename(2) in overwriting the destination if it exists atomically (meaning that no other process will see the destination cease to exist, even for an instant).  This is useful because it allows you to build a file as a temp file, then rename it to where you want it to be, and nobody sees the file when it's half done.
Probably rename($old, $new) with an existing new was caused by permission problems.  I bet the other problems you had were the result of not calling clearstatcache(), which can cause PHP to act like a file exists though it has since been deleted.


dev

- rename extension of files
changeext($directory, $ext1, $ext2, $verbose)
i wrote this function to rename the extention of some files in a folder and sub-folders inside it ..
parameter 1 :  the directory name
parameter 2 :  the first extention wich we want to replace
parameter 3 :  the new extention of files
for a simple usage call the function :
changeext('dir', 'html', 'php',  'false');
to change evry file name with extention html  into php  in the directory  dir
<?php
function changeext($directory, $ext1, $ext2, $verbose = false) {
 $num = 0;
 if($curdir = opendir($directory)) {
  while($file = readdir($curdir)) {
    if($file != '.' && $file != '..') {
      $srcfile = $directory . '/' . $file;
      $string  = "$file";
      $str     = strlen($ext1);
      $str++;
      $newfile = substr($string, 0, -$str);
      $newfile = $newfile.'.'.$ext2;
      $dstfile = $directory . '/' . $newfile;
      if (eregi("\.$ext1",$file)) { # Look at only files with a pre-defined extension
      $fileHand = fopen($srcfile, 'r');
      fclose($fileHand);
      rename($srcfile, $dstfile );
      }
      if(is_dir($srcfile)) {
        $num += changeext($srcfile, $ext1, $ext2, $verbose);
      }
    }
  }
  closedir($curdir);
 }
 return $num;
}
changeext('dir', 'html', 'php',  'false');
?>
to remove the extention of files , just leave the parameter $ext2 blank ''


Change Language


Follow Navioo On Twitter
basename
chgrp
chmod
chown
clearstatcache
copy
delete
dirname
disk_free_space
disk_total_space
diskfreespace
fclose
feof
fflush
fgetc
fgetcsv
fgets
fgetss
file_exists
file_get_contents
file_put_contents
file
fileatime
filectime
filegroup
fileinode
filemtime
fileowner
fileperms
filesize
filetype
flock
fnmatch
fopen
fpassthru
fputcsv
fputs
fread
fscanf
fseek
fstat
ftell
ftruncate
fwrite
glob
is_dir
is_executable
is_file
is_link
is_readable
is_uploaded_file
is_writable
is_writeable
lchgrp
lchown
link
linkinfo
lstat
mkdir
move_uploaded_file
parse_ini_file
pathinfo
pclose
popen
readfile
readlink
realpath
rename
rewind
rmdir
set_file_buffer
stat
symlink
tempnam
tmpfile
touch
umask
unlink
eXTReMe Tracker