function FileSystem::prepareDestination

Same name in other branches
  1. 9 core/lib/Drupal/Core/File/FileSystem.php \Drupal\Core\File\FileSystem::prepareDestination()
  2. 8.9.x core/lib/Drupal/Core/File/FileSystem.php \Drupal\Core\File\FileSystem::prepareDestination()
  3. 11.x core/lib/Drupal/Core/File/FileSystem.php \Drupal\Core\File\FileSystem::prepareDestination()

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.

\Drupal\Core\File\FileExists|int $fileExists: Replace behavior when the destination file already exists.

Throws

\TypeError Thrown when the $fileExists parameter is not an enum or legacy int.

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
FileSystem::move in core/lib/Drupal/Core/File/FileSystem.php

File

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

Class

FileSystem
Provides helpers to operate on files and stream wrappers.

Namespace

Drupal\Core\File

Code

protected function prepareDestination($source, &$destination, $fileExists) {
    if (!$fileExists instanceof FileExists) {
        // @phpstan-ignore-next-line
        $fileExists = FileExists::fromLegacyInt($fileExists, __METHOD__);
    }
    $original_source = $source;
    if (!file_exists($source)) {
        if (($realpath = $this->realpath($original_source)) !== FALSE) {
            throw new FileNotExistsException("File '{$original_source}' ('{$realpath}') could not be copied because it does not exist.");
        }
        else {
            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)) {
            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, $fileExists);
    if ($destination === FALSE) {
        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) {
        throw new FileException("File '{$source}' could not be copied because it would overwrite itself.");
    }
}

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