Home › API reference › file.inc

file_destination

  1. drupal
    1. 6
    2. 7
Versions
6 – 7 file_destination($destination, $replace)

Determines the destination path for a file depending on how replacement of existing files should be handled.

Parameters

$destination A string specifying the desired final URI or filepath.

$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 destination filepath, or FALSE if the file already exists and FILE_EXISTS_ERROR is specified.

Related topics

File interface
Common file handling functions.

▸ 2 functions call file_destination()

▾ 2 functions call file_destination()

file_save_upload in drupal/includes/file.inc
Saves a file upload to a new location.
file_unmanaged_copy in drupal/includes/file.inc
Copies a file to a new location without invoking the file API.

Code

drupal/includes/file.inc, line 935

<?php
function file_destination($destination, $replace) {
  if (file_exists($destination)) {
    switch ($replace) {
      case FILE_EXISTS_REPLACE:
        // Do nothing here, we want to overwrite the existing file.
        break;

      case FILE_EXISTS_RENAME:
        $basename = basename($destination);
        $directory = drupal_dirname($destination);
        $destination = file_create_filename($basename, $directory);
        break;

      case FILE_EXISTS_ERROR:
        // Error reporting handled by calling function.
        return FALSE;
    }
  }
  return $destination;
}
?>