file_copy

• Drupal 4.6
• Drupal 4.7
• Drupal 5
• Drupal 6
• Drupal 7

Versions

4.6 – 6

file_copy(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME)

7

file_copy(stdClass $source, $destination = NULL, $replace = FILE_EXISTS_RENAME)

Copy a file to a new location and adds a file record to the database.

This function should be used when manipulating files that have records stored in the database. This is a powerful function that in many ways performs like an advanced version of copy().

• 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.
• Adds the new file to the files database. If the source file is a temporary file, the resulting file will also be a temporary file. @see file_save_upload() for details on temporary files.

See also

file_unmanaged_copy()

@see hook_file_copy()

Parameters

$source A file object.

$destination A string containing the destination that $source should be copied to. This should be a stream wrapper URI. If this value is omitted, Drupal's public files scheme will be used, "public://".

$replace Replace behavior when the destination file already exists:

• FILE_EXISTS_REPLACE - Replace the existing file. If a managed file with the destination name exists then its database entry will be updated. If no database entry is found then a new one will be created.
• FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is unique.
• FILE_EXISTS_ERROR - Do nothing and return FALSE.

Return value

File object if the copy is successful, or FALSE in the event of an error.

Related topics

File interface

Common file handling functions.

Code

includes/file.inc, line 532

<?php
function file_copy(stdClass $source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
  if ($uri = file_unmanaged_copy($source->uri, $destination, $replace)) {
    $file = clone $source;
    $file->fid = NULL;
    $file->uri = $uri;
    $file->filename = basename($uri);
    // If we are replacing an existing file re-use its database record.
    if ($replace == FILE_EXISTS_REPLACE) {
      $existing_files = file_load_multiple(array(), array('uri' => $uri));
      if (count($existing_files)) {
        $existing = reset($existing_files);
        $file->fid = $existing->fid;
        $file->filename = $existing->filename;
      }
    }
    // If we are renaming around an existing file (rather than a directory),
    // use its basename for the filename.
    elseif ($replace == FILE_EXISTS_RENAME && is_file($destination)) {
      $file->filename = basename($destination);
    }

    $file = file_save($file);

    // Inform modules that the file has been copied.
    module_invoke_all('file_copy', $file, $source);

    return $file;
  }
  return FALSE;
}
?>

Login or register to post comments