1 file.inc | file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) |
Copies a file to a new location without database changes or hook invocation.
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.
Parameters
$source: A string specifying the filepath or URI of the source file.
$destination: A URI containing the destination that $source should be copied to. The URI may be a bare filepath (without a scheme). If this value is omitted, Backdrop'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
The path to the new file, or FALSE in the event of an error.:
See also
Related topics
File
- core/
includes/ file.inc, line 904 - API for handling file uploads and server file management.
Code
function file_unmanaged_copy($source, $destination = NULL, $replace = FILE_EXISTS_RENAME) {
if (!file_unmanaged_prepare($source, $destination, $replace)) {
return FALSE;
}
// Attempt to resolve the URIs. This is necessary in certain configurations
// (see above).
$real_source = ($real_source = backdrop_realpath($source)) ? $real_source : $source;
$real_destination = ($real_destination = backdrop_realpath($destination)) ? $real_destination : $destination;
// Perform the copy operation.
if (!@copy($real_source, $real_destination)) {
watchdog('file', 'The specified file %file could not be copied to %destination.', array('%file' => $source, '%destination' => $destination), WATCHDOG_ERROR);
return FALSE;
}
// Set the permissions on the new file.
backdrop_chmod($destination);
return $destination;
}