function file_copy in Zircon Profile 8
Same name and namespace in other branches
- 8.0 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. FILE_EXISTS_REPLACE will error out. FILE_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: Replace behavior when the destination file already exists:
- FILE_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.
- FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is unique.
- FILE_EXISTS_ERROR - Do nothing and return FALSE.
Return value
\Drupal\file\FileInterface|FALSE File object if the copy is successful, or FALSE in the event of an error.
See also
5 calls to file_copy()
- CopyTest::testExistingError in core/
modules/ file/ src/ Tests/ CopyTest.php - Test that copying over an existing file fails when FILE_EXISTS_ERROR is specified.
- CopyTest::testExistingRename in core/
modules/ file/ src/ Tests/ CopyTest.php - Test renaming when copying over a file that already exists.
- CopyTest::testExistingReplace in core/
modules/ file/ src/ Tests/ CopyTest.php - Test replacement when copying over a file that already exists.
- CopyTest::testNormal in core/
modules/ file/ src/ Tests/ CopyTest.php - Test file copying in the normal, base case.
- FileTokenReplaceTest::testFileTokenReplacement in core/
modules/ file/ src/ Tests/ FileTokenReplaceTest.php - Creates a file, then tests the tokens generated from it.
File
- core/
modules/ file/ file.module, line 137 - Defines a "managed_file" Form API field and a "file" field for Field module.
Code
function file_copy(FileInterface $source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
if (!file_valid_uri($destination)) {
if (($realpath = drupal_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.', array(
'%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.', array(
'%file' => $source
->getFileUri(),
'%destination' => $destination,
));
}
drupal_set_message(t('The specified file %file could not be copied because the destination is invalid. More information is available in the system log.', array(
'%file' => $source
->getFileUri(),
)), 'error');
return FALSE;
}
if ($uri = file_unmanaged_copy($source
->getFileUri(), $destination, $replace)) {
$file = $source
->createDuplicate();
$file
->setFileUri($uri);
$file
->setFilename(drupal_basename($uri));
// If we are replacing an existing file re-use its database record.
// @todo Do not create a new entity in order to update it. See
// https://www.drupal.org/node/2241865.
if ($replace == FILE_EXISTS_REPLACE) {
$existing_files = entity_load_multiple_by_properties('file', array(
'uri' => $uri,
));
if (count($existing_files)) {
$existing = reset($existing_files);
$file->fid = $existing
->id();
$file
->setOriginalId($existing
->id());
$file
->setFilename($existing
->getFilename());
}
}
elseif ($replace == FILE_EXISTS_RENAME && is_file($destination)) {
$file
->setFilename(drupal_basename($destination));
}
$file
->save();
// Inform modules that the file has been copied.
\Drupal::moduleHandler()
->invokeAll('file_copy', array(
$file,
$source,
));
return $file;
}
return FALSE;
}