function file_unmanaged_move

Moves a file to a new location without database changes or hook invocation. This is a powerful function that in many ways performs like an advanced version of rename().

• Checks if $source and $destination are valid and readable/writable.
• Checks that $source is not equal to $destination; if they are an error is reported.
• If file already exists in $destination either the call will error out, replace the file or rename the file based on the $replace parameter.
• Works around a PHP 5.3 bug where rename() does not properly support streams if safe_mode or open_basedir are enabled.

Parameters

$source: A string specifying the filepath or URI of the source file.

$destination: A URI containing the destination that $source should be moved to. The URI may be a bare filepath (without a scheme) and in that case the default scheme (file://) will be used. If this value is omitted, Backdrop's default files scheme will be used, usually "public://".

$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

The path to the new file, or FALSE in the event of an error.:

See also

https://bugs.php.net/bug.php?id=60456

file_move()

Related topics

File

includes/file.inc, line 1165

API for handling file uploads and server file management.

Code

function file_unmanaged_move($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
  if (!file_unmanaged_prepare($source, $destination, $replace)) {
    return FALSE;
  }
  // The file must be writable in the old location before moving.
  backdrop_chmod($source);
  // Attempt to resolve the URIs. This is necessary in certain configurations
  // (see above) and can also permit fast moves across local schemes.
  $real_source = ($real_source = backdrop_realpath($source)) ? $real_source : $source;
  $real_destination = ($real_destination = backdrop_realpath($destination)) ? $real_destination : $destination;
  // Perform the move operation.
  if (!@rename($real_source, $real_destination)) {
    // Fall back to slow copy and unlink procedure. This is necessary for
    // renames across schemes that are not local, or where rename() has not been
    // implemented.
    if (!@copy($real_source, $real_destination) || !@unlink($real_source)) {
      watchdog('file', 'The specified file %file could not be moved to %destination.', array('%file' => $source, '%destination' => $destination), WATCHDOG_ERROR);
      return FALSE;
    }
  }
  // Set the permissions on the new file.
  backdrop_chmod($destination);
  return $destination;
}