Prepares the destination for a file copy or move operation.

• 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

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

string|null $destination: A URI containing the destination that $source should be moved/copied to. The URI may be a bare filepath (without a scheme) and in that case the default scheme (file://) will be used.

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 - Do nothing and return FALSE.

See also

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

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

2 calls to FileSystem::prepareDestination()

FileSystem::copy in core/lib/Drupal/Core/File/FileSystem.php

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

FileSystem::move in core/lib/Drupal/Core/File/FileSystem.php

Moves a file to a new location without database changes or hook invocation.

File

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

Class

FileSystem

Provides helpers to operate on files and stream wrappers.

Namespace

Drupal\Core\File

Code

protected function prepareDestination($source, &$destination, $replace) {
  $original_source = $source;
  if (!file_exists($source)) {
    if (($realpath = $this->realpath($original_source)) !== FALSE) {
      $this->logger
        ->error("File '%original_source' ('%realpath') could not be copied because it does not exist.", [
        '%original_source' => $original_source,
        '%realpath' => $realpath,
      ]);
      throw new FileNotExistsException("File '{$original_source}' ('{$realpath}') could not be copied because it does not exist.");
    }
    else {
      $this->logger
        ->error("File '%original_source' could not be copied because it does not exist.", [
        '%original_source' => $original_source,
      ]);
      throw new FileNotExistsException("File '{$original_source}' could not be copied because it does not exist.");
    }
  }
  // Prepare the destination directory.
  if ($this->prepareDirectory($destination)) {
    // The destination is already a directory, so append the source basename.
    $destination = $this->streamWrapperManager
      ->normalizeUri($destination . '/' . $this->basename($source));
  }
  else {
    // Perhaps $destination is a dir/file?
    $dirname = $this->dirname($destination);
    if (!$this->prepareDirectory($dirname)) {
      $this->logger
        ->error("The specified file '%original_source' could not be copied because the destination directory '%destination_directory' is not properly configured. This may be caused by a problem with file or directory permissions.", [
        '%original_source' => $original_source,
        '%destination_directory' => $dirname,
      ]);
      throw new DirectoryNotReadyException("The specified file '{$original_source}' could not be copied because the destination directory '{$dirname}' is not properly configured. This may be caused by a problem with file or directory permissions.");
    }
  }
  // Determine whether we can perform this operation based on overwrite rules.
  $destination = $this->getDestinationFilename($destination, $replace);
  if ($destination === FALSE) {
    $this->logger
      ->error("File '%original_source' could not be copied because a file by that name already exists in the destination directory ('%destination').", [
      '%original_source' => $original_source,
      '%destination' => $destination,
    ]);
    throw new FileExistsException("File '{$original_source}' could not be copied because a file by that name already exists in the destination directory ('{$destination}').");
  }
  // Assert that the source and destination filenames are not the same.
  $real_source = $this->realpath($source);
  $real_destination = $this->realpath($destination);
  if ($source == $destination || $real_source !== FALSE && $real_source == $real_destination) {
    $this->logger
      ->error("File '%source' could not be copied because it would overwrite itself.", [
      '%source' => $source,
    ]);
    throw new FileException("File '{$source}' could not be copied because it would overwrite itself.");
  }
}

---