Breaking this off from #1191236: Correct file_copy, file_move, file_save_data, and drupal_realpath to match documentation and their unmanaged counterparts.

The documentation for the $destination parameter to file_copy() say, in part:

If this value is omitted, Drupal's default files scheme will be used, usually "public://".

However, this claim is untrue. Omitting the $destination parameter will actually result in the following code being executed:

    watchdog('file', '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->uri, '%realpath' => drupal_realpath($\
source->uri), '%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->uri)), 'error');
    return FALSE;
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

pillarsdotnet’s picture

Status: Active » Needs review
FileSize
1.16 KB

The following patch corrects the documentation to match the code.

pillarsdotnet’s picture

Title: Correct docs of file_copy() to match implementation. » Make docs of file_copy() match code.
Issue tags: +Needs backport to D7
jhodgdon’s picture

Status: Needs review » Needs work

I don't think it's necessary to say what happens if the value is omitted. Just say it's required, or better yet just don't say anything, because we all know that PHP function arguments are generally required unless they are stated to be optional. We don't want to set a precedent of documenting what happens if people leave out required args in every function in Drupal.

pillarsdotnet’s picture

Status: Needs work » Needs review
FileSize
1.07 KB

Corrected as suggested. See also alternative proposal #1192446: Make code of file_copy() match docs.

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

Looks fine.

webchick’s picture

Status: Reviewed & tested by the community » Fixed

Committed to 8.x and 7.x. Thanks!

Automatically closed -- issue fixed for 2 weeks with no activity.