Same name in other branches

1. 7.x includes/file.inc \file_copy()
2. 8.9.x core/modules/file/file.module \file_copy()

Copies 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.
• 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. FileSystemInterface::EXISTS_REPLACE will error out. FileSystemInterface::EXISTS_RENAME will rename the file until the $destination is unique.
• 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.

Parameters

\Drupal\file\FileInterface $source: A file entity.

string $destination: A string containing the destination that $source should be copied to. This must be a stream wrapper URI.

int $replace: (optional) Replace behavior when the destination file already exists. Possible values include:

• FileSystemInterface::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.
• FileSystemInterface::EXISTS_RENAME: (default) Append _{incrementing number} until the filename is unique.
• FileSystemInterface::EXISTS_ERROR: Do nothing and return FALSE.

Return value

\Drupal\file\FileInterface|false File entity if the copy is successful, or FALSE in the event of an error.

Throws

\Drupal\Core\Entity\EntityStorageException Thrown when there is an error updating the file storage.

See also

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

\Drupal\file\FileRepositoryInterface::copy()

\Drupal\Core\File\FileSystemInterface::copy()

hook_file_copy()

1 call to file_copy()

LegacyFileTest::testCopy in core/modules/file/tests/src/Kernel/LegacyFileTest.php

Tests the file_copy deprecation and legacy behavior.

6 string references to 'file_copy'

d6_file.yml in core/modules/file/migrations/d6_file.yml

core/modules/file/migrations/d6_file.yml

d6_user_picture_file.yml in core/modules/user/migrations/d6_user_picture_file.yml

core/modules/user/migrations/d6_user_picture_file.yml

d7_file.yml in core/modules/file/migrations/d7_file.yml

core/modules/file/migrations/d7_file.yml

d7_file_private.yml in core/modules/file/migrations/d7_file_private.yml

core/modules/file/migrations/d7_file_private.yml

d7_file_used.yml in core/modules/file/tests/modules/file_test_get_ids/migrations/d7_file_used.yml

core/modules/file/tests/modules/file_test_get_ids/migrations/d7_file_used.yml

... See full list

File

core/modules/file/file.module, line 136

Code

function file_copy(FileInterface $source, $destination = NULL, $replace = FileSystemInterface::EXISTS_RENAME) {
    @trigger_error(__FUNCTION__ . ' is deprecated in drupal:9.3.0 and will be removed in drupal:10.0.0. Use \\Drupal\\file\\FileRepositoryInterface::copy() instead. See https://www.drupal.org/node/3223520', E_USER_DEPRECATED);
    if (empty($destination)) {
        $destination = \Drupal::config('system.file')->get('default_scheme') . '://';
    }
    
    /** @var \Drupal\file\FileRepositoryInterface $file_repository */
    $file_repository = \Drupal::service('file.repository');
    try {
        return $file_repository->copy($source, $destination, $replace);
    } catch (InvalidStreamWrapperException $e) {
        if (($realpath = \Drupal::service('file_system')->realpath($source->getFileUri())) !== FALSE) {
            \Drupal::logger('file')->notice('File %file (%realpath) could not be copied because the destination %destination is invalid. This is often caused by improper use of file_copy() or a missing stream wrapper.', [
                '%file' => $source->getFileUri(),
                '%realpath' => $realpath,
                '%destination' => $destination,
            ]);
        }
        else {
            \Drupal::logger('file')->notice('File %file could not be copied because the destination %destination is invalid. This is often caused by improper use of file_copy() or a missing stream wrapper.', [
                '%file' => $source->getFileUri(),
                '%destination' => $destination,
            ]);
        }
        \Drupal::messenger()->addError(t('The specified file %file could not be copied because the destination is invalid. More information is available in the system log.', [
            '%file' => $source->getFileUri(),
        ]));
        return FALSE;
    } catch (FileException $e) {
        return FALSE;
    }
}

---