file_move

Versions
4.6 – 6: file_move(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME)
7: file_move(stdClass $source, $destination = NULL, $replace = FILE_EXISTS_RENAME)

Moves a file to a new location.

Checks if $source and $dest are valid and readable/writable.
Performs a file move if $source is not equal to $dest.
If file already exists in $dest either the call will error out, replace the file or rename the file based on the $replace parameter.

Parameters

$source A string specifying the file location of the original file. This parameter will contain the resulting destination filename in case of success.

$dest A string containing the directory $source should be copied to. If this value is omitted, Drupal's 'files' directory will be used.

$replace Replace behavior when the destination file already exists.

FILE_EXISTS_REPLACE - Replace the existing file
FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is unique
FILE_EXISTS_ERROR - Do nothing and return FALSE.

Return value

True for success, FALSE for failure.

▸ 1 function calls file_move()

▾ 1 function calls file_move()

file_save_data in includes/file.inc: Save a string to the specified destination.

Code

includes/file.inc, line 329

<?php
function file_move(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME) {
  $path_original = is_object($source) ? $source->filepath : $source;

  if (file_copy($source, $dest, $replace)) {
    $path_current = is_object($source) ? $source->filepath : $source;

    if ($path_original == $path_current || file_delete($path_original)) {
      return 1;
    }
    drupal_set_message(t('The removal of the original file %file has failed.', array('%file' => $path_original)), 'error');
  }
  return 0;
}
?>

clarification: $dest can be a full path + new filename

jimrockford - Wed, 2009-11-25 08:29

The above documentation may appear to suggest the filename in $source will always become the filename of the $dest file. Also, it implies $dest must be a folder/directory, rather than a path+filename . In D6.14 I've used file_move() as follows:

file_move("/uploads/abc.txt", "/uploads/def.txt"); // rename, keep in same dir

file_move("/uploads/mno.txt", "/uploads/converted/xyz.txt"); // move and rename

This is like unix mv command, and maybe windows, but hopefully my comment will save someone from having to test it all to see if it works for renaming. I've only tried this with absolute paths.