file_unmanaged_copy

  1. drupal
    1. 8
    2. 7
Versions
7 – 8 file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME)

Copies a file to a new location without invoking the file API.

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.

Parameters

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

$destination A URI containing the destination that $source should be copied 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, Drupal's default files scheme will be used, usually "public://".

$replace Replace behavior when the destination file already exists:

Return value

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

See also

file_copy()

Related topics

▾ 10 functions call file_unmanaged_copy()

color_scheme_form_submit in modules/color/color.module
Submit handler for color change form.
DrupalWebTestCase::drupalGetTestFiles in modules/simpletest/drupal_web_test_case.php
Get a list files that can be used in tests.
FileUnmanagedCopyTest::testNonExistent in modules/simpletest/tests/file.test
Copy a non-existent file.
FileUnmanagedCopyTest::testNormal in modules/simpletest/tests/file.test
Copy a normal file.
FileUnmanagedCopyTest::testOverwriteSelf in modules/simpletest/tests/file.test
Copy a file onto itself.
file_copy in includes/file.inc
Copies a file to a new location and adds a file record to the database.
file_unmanaged_move in includes/file.inc
Move a file to a new location without calling any hooks or making any changes to the database.
ImageAdminStylesUnitTest::createSampleImage in modules/image/image.test
Given an image style, generate an image.
ImageStylesPathAndUrlUnitTest::_testImageStyleUrlAndPath in modules/image/image.test
Test image_style_url().
system_theme_settings_submit in modules/system/system.admin.inc
Process system_theme_settings form submissions.

Code

includes/file.inc, line 851

<?php
function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
  $original_source = $source;
  $original_destination = $destination;

  // Assert that the source file actually exists.
  if (!file_exists($source)) {
    // @todo Replace drupal_set_message() calls with exceptions instead.
    drupal_set_message(t('The specified file %file could not be copied, because no file by that name exists. Please check that you supplied the correct filename.', array('%file' => $original_source)), 'error');
    if (($realpath = drupal_realpath($original_source)) !== FALSE) {
      watchdog('file', 'File %file (%realpath) could not be copied because it does not exist.', array('%file' => $original_source, '%realpath' => $realpath));
    }
    else {
      watchdog('file', 'File %file could not be copied because it does not exist.', array('%file' => $original_source));
    }
    return FALSE;
  }

  // Build a destination URI if necessary.
  if (!isset($destination)) {
    $destination = file_build_uri(basename($source));
  }


  // Prepare the destination directory.
  if (file_prepare_directory($destination)) {
    // The destination is already a directory, so append the source basename.
    $destination = file_stream_wrapper_uri_normalize($destination . '/' . basename($source));
  }
  else {
    // Perhaps $destination is a dir/file?
    $dirname = drupal_dirname($destination);
    if (!file_prepare_directory($dirname)) {
      // The destination is not valid.
      watchdog('file', 'File %file could not be copied, because the destination directory %destination is not configured correctly.', array('%file' => $original_source, '%destination' => $dirname));
      drupal_set_message(t('The specified file %file could not be copied, because the destination directory is not properly configured. This may be caused by a problem with file or directory permissions. More information is available in the system log.', array('%file' => $original_source)), 'error');
      return FALSE;
    }
  }

  // Determine whether we can perform this operation based on overwrite rules.
  $destination = file_destination($destination, $replace);
  if ($destination === FALSE) {
    drupal_set_message(t('The file %file could not be copied because a file by that name already exists in the destination directory.', array('%file' => $original_source)), 'error');
    watchdog('file', 'File %file could not be copied because a file by that name already exists in the destination directory (%directory)', array('%file' => $original_source, '%destination' => $destination));
    return FALSE;
  }

  // Assert that the source and destination filenames are not the same.
  $real_source = drupal_realpath($source);
  $real_destination = drupal_realpath($destination);
  if ($source == $destination || ($real_source !== FALSE) && ($real_source == $real_destination)) {
    drupal_set_message(t('The specified file %file was not copied because it would overwrite itself.', array('%file' => $source)), 'error');
    watchdog('file', 'File %file could not be copied because it would overwrite itself.', array('%file' => $source));
    return FALSE;
  }
  // Make sure the .htaccess files are present.
  file_ensure_htaccess();
  // Perform the copy operation.
  if (!@copy($source, $destination)) {
    watchdog('file', 'The specified file %file could not be copied to %destination.', array('%file' => $source, '%destination' => $destination), WATCHDOG_ERROR);
    return FALSE;
  }

  // Set the permissions on the new file.
  drupal_chmod($destination);

  return $destination;
}
?>