function file_unmanaged_copy

Same name in other branches
  1. 7.x includes/file.inc \file_unmanaged_copy()

Copies 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 copy().

  • Checks if $source and $destination are valid and readable/writable.
  • If file already exists in $destination either the call will error out, replace the file or rename the file based on the $replace parameter.
  • If the $source and $destination are equal, the behavior depends on the $replace parameter. FILE_EXISTS_REPLACE will error out. FILE_EXISTS_RENAME will rename the file until the $destination is unique.
  • Works around a PHP bug where copy() 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 copied to. The URI may be a bare filepath (without a scheme). 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.

Deprecated

in drupal:8.7.0 and is removed from drupal:9.0.0. Use \Drupal\Core\File\FileSystemInterface::copy().

See also

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

file_copy()

https://www.drupal.org/node/3006851

Related topics

1 call to file_unmanaged_copy()
FileSystemDeprecationTest::testDeprecatedUnmanagedFileCopy in core/tests/Drupal/KernelTests/Core/File/FileSystemDeprecationTest.php
@expectedDeprecation file_unmanaged_copy() is deprecated in Drupal 8.7.0 and will be removed before Drupal 9.0.0. Use \Drupal\Core\File\FileSystemInterface::copy(). See https://www.drupal.org/node/3006851.

File

core/includes/file.inc, line 444

Code

function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
    @trigger_error('file_unmanaged_copy() is deprecated in Drupal 8.7.0 and will be removed before Drupal 9.0.0. Use \\Drupal\\Core\\File\\FileSystemInterface::copy(). See https://www.drupal.org/node/3006851.', E_USER_DEPRECATED);
    try {
        $file_system = \Drupal::service('file_system');
        // Build a destination URI if necessary.
        if (!isset($destination)) {
            $destination = file_build_uri($file_system->basename($source));
        }
        return $file_system->copy($source, $destination, $replace);
    } catch (FileException $e) {
        return FALSE;
    }
}

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.