Internal function that prepares the destination for a file_unmanaged_copy or file_unmanaged_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

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

$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. If this value is omitted, Drupal's default files scheme will be used, usually "public://".

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

• FILE_EXISTS_REPLACE - Replace the existing file.
• FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is unique.
• FILE_EXISTS_ERROR - Do nothing and return FALSE.

Return value

TRUE, or FALSE in the event of an error.

See also

file_unmanaged_copy()

file_unmanaged_move()

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

Related topics

1 call to file_unmanaged_prepare()

FileSystemDeprecationTest::testDeprecatedUnmanagedPrepare in core/tests/Drupal/KernelTests/Core/File/FileSystemDeprecationTest.php

@expectedDeprecation file_unmanaged_prepare() is deprecated in Drupal 8.7.0 and will be removed before Drupal 9.0.0. Use \Drupal\Core\File\FileSystemInterface::getDestinationFilename() instead. See https://www.drupal.org/node/3006851.

File

core/includes/file.inc, line 494

Code

function file_unmanaged_prepare($source, &$destination = NULL, $replace = FILE_EXISTS_RENAME) {
    @trigger_error('file_unmanaged_prepare() is deprecated in Drupal 8.7.0 and will be removed before Drupal 9.0.0. Use \\Drupal\\Core\\File\\FileSystemInterface::getDestinationFilename() instead. See https://www.drupal.org/node/3006851.', E_USER_DEPRECATED);
    $original_source = $source;
    $logger = \Drupal::logger('file');
    
    /** @var \Drupal\Core\File\FileSystemInterface $file_system */
    $file_system = \Drupal::service('file_system');
    // Assert that the source file actually exists.
    if (!file_exists($source)) {
        // @todo Replace \Drupal::messenger()->addError() calls with exceptions
        // instead.
        \Drupal::messenger()->addError(t('The specified file %file could not be moved/copied because no file by that name exists. Please check that you supplied the correct filename.', [
            '%file' => $original_source,
        ]));
        if (($realpath = $file_system->realpath($original_source)) !== FALSE) {
            $logger->notice('File %file (%realpath) could not be moved/copied because it does not exist.', [
                '%file' => $original_source,
                '%realpath' => $realpath,
            ]);
        }
        else {
            $logger->notice('File %file could not be moved/copied because it does not exist.', [
                '%file' => $original_source,
            ]);
        }
        return FALSE;
    }
    // Build a destination URI if necessary.
    if (!isset($destination)) {
        $destination = file_build_uri($file_system->basename($source));
    }
    // Prepare the destination directory.
    if (file_prepare_directory($destination)) {
        // The destination is already a directory, so append the source basename.
        $destination = file_stream_wrapper_uri_normalize($destination . '/' . $file_system->basename($source));
    }
    else {
        // Perhaps $destination is a dir/file?
        $dirname = $file_system->dirname($destination);
        if (!file_prepare_directory($dirname)) {
            // The destination is not valid.
            $logger->notice('File %file could not be moved/copied because the destination directory %destination is not configured correctly.', [
                '%file' => $original_source,
                '%destination' => $dirname,
            ]);
            \Drupal::messenger()->addError(t('The specified file %file could not be moved/copied because the destination directory is not properly configured. This may be caused by a problem with file or directory permissions. More information is available in the system log.', [
                '%file' => $original_source,
            ]));
            return FALSE;
        }
    }
    // Determine whether we can perform this operation based on overwrite rules.
    $destination = file_destination($destination, $replace);
    if ($destination === FALSE) {
        \Drupal::messenger()->addError(t('The file %file could not be moved/copied because a file by that name already exists in the destination directory.', [
            '%file' => $original_source,
        ]));
        $logger->notice('File %file could not be moved/copied because a file by that name already exists in the destination directory (%destination)', [
            '%file' => $original_source,
            '%destination' => $destination,
        ]);
        return FALSE;
    }
    // Assert that the source and destination filenames are not the same.
    $real_source = $file_system->realpath($source);
    $real_destination = $file_system->realpath($destination);
    if ($source == $destination || $real_source !== FALSE && $real_source == $real_destination) {
        \Drupal::messenger()->addError(t('The specified file %file was not moved/copied because it would overwrite itself.', [
            '%file' => $source,
        ]));
        $logger->notice('File %file could not be moved/copied because it would overwrite itself.', [
            '%file' => $source,
        ]);
        return FALSE;
    }
    // Make sure the .htaccess files are present.
    file_ensure_htaccess();
    return TRUE;
}

---