Same name and namespace in other branches

1. 8.9.x core/lib/Drupal/Core/File/FileSystem.php \Drupal\Core\File\FileSystem::copy()
2. 10 core/lib/Drupal/Core/File/FileSystem.php \Drupal\Core\File\FileSystem::copy()
3. 11.x core/lib/Drupal/Core/File/FileSystem.php \Drupal\Core\File\FileSystem::copy()

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.
• 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 replace the existing file. FileSystemInterface::EXISTS_ERROR will error out. FileSystemInterface::EXISTS_RENAME will rename the file until the $destination is unique.
• Provides a fallback using realpaths if the move fails using stream wrappers. This can occur because PHP's copy() function does not properly support streams if open_basedir is enabled. See https://bugs.php.net/bug.php?id=60456

Parameters

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

string $destination: A URI containing the destination that $source should be copied to. The URI may be a bare filepath (without a scheme).

int $replace: Replace behavior when the destination file already exists:

• FileSystemInterface::EXISTS_REPLACE - Replace the existing file.
• FileSystemInterface::EXISTS_RENAME - Append _{incrementing number} until the filename is unique.
• FileSystemInterface::EXISTS_ERROR - Throw an exception.

Return value

string The path to the new file.

Overrides FileSystemInterface::copy

File

core/lib/Drupal/Core/File/FileSystem.php, line 296

Class

FileSystem

Provides helpers to operate on files and stream wrappers.

Namespace

Drupal\Core\File

Code

public function copy($source, $destination, $replace = self::EXISTS_RENAME) {
    $this->prepareDestination($source, $destination, $replace);
    if (!@copy($source, $destination)) {
        // If the copy failed and realpaths exist, retry the operation using them
        // instead.
        $real_source = $this->realpath($source) ?: $source;
        $real_destination = $this->realpath($destination) ?: $destination;
        if ($real_source === FALSE || $real_destination === FALSE || !@copy($real_source, $real_destination)) {
            $this->logger
                ->error("The specified file '%source' could not be copied to '%destination'.", [
                '%source' => $source,
                '%destination' => $destination,
            ]);
            throw new FileWriteException("The specified file '{$source}' could not be copied to '{$destination}'.");
        }
    }
    // Set the permissions on the new file.
    $this->chmod($destination);
    return $destination;
}

---