FileSystemInterface::copy documentation is inaccurate

There was error in patch. I've fixed it & added.

drupal-file_unmanaged_copy_docs-2843100.patch:19: trailing whitespace.
 *   will assign a new unique name (@see file_create_filename()). 
Checking patch core/includes/file.inc...
Applied patch core/includes/file.inc cleanly.
warning: 1 line adds whitespace errors.

Looks good.

Thanks all for working on this but I think this still needs some improvement.

+++ b/core/includes/file.inc
@@ -419,11 +419,12 @@ function file_valid_uri($uri) {
- * - 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.
+ * - If $source and $destination are equal, return false. Do not overwrite a
+ *   file with itself.
+ * - If file already exists in $destination, the behavior depends on the
+ *   $replace parameter. FILE_EXISTS_ERROR will return false,
+ *   FILE_EXISTS_REPLACE will replace the existing file, and FILE_EXISTS_RENAME
+ *   will assign a new unique name (@see file_create_filename()).

This looses "error out" which may mean it just logs an error, but that would still be useful to document (I guess keep documented even though it was/is misleadingly documented).

The new first item is not describing the behavior from the consumer/user side but from the function, which is in stark contrast to the item above and below.

Modified as per suggestion in #9.

Looks good to me. +1 to RTBC

Tested #10 on 9.1. It appears fine to me as well
RTBC + 1

Patch can't be applied on 9.2.x dev .Showing error

Checking patch core/includes/file.inc...
error: while searching for:
 *
 * 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.
 * - Works around a PHP bug where copy() does not properly support streams if
 *   safe_mode or open_basedir are enabled.
 *   @see https://bugs.php.net/bug.php?id=60456

error: patch failed: core/includes/file.inc:428
error: core/includes/file.inc: patch does not apply

Patch for 9.3

file_unmanaged_copy was removed from core in Drupal 9.0 (deprecated in 8.7.0).

The new docs are on \Drupal\Core\File\FileSystemInterface::copy and that's where the updating should occur.

Rerolled the Patch against 9.3.x. Please review
Updated the docs in \Drupal\Core\File\FileSystemInterface::copy

+   * - If file already exists in $destination, the behavior depends on the
+   *   $replace parameter. FILE_EXISTS_ERROR will error out,
+   *   FILE_EXISTS_REPLACE will replace the existing file, and FILE_EXISTS_RENAME
+   *   will assign a new unique name (@see createFilename()).

If I understand the coding standards for @see, the method name must include the fully qualified name of its class. @see needs to be on its own line, which in this case means it should be placed after that list.

Addressed #30 with an interdiff.

The method name must contain the class name, namespace included.

patch #33 applied cleanly on D9.4.x.

patch #33 applied cleanly on D9.5.x.

Change in #33 seems fine too me.

I don't think this is right.

https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21File%21Fi... - this throws an exception if $source and $destination are the same.

Exception is also documented here: https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21File%21Fi...

Also the issue summary is still referencing the procedural functions that were removed a long time ago.

Updated issue summary and created an MR.

Added example and updated $fileExists parameters.

thanks for the fix

Oh, nice to see the quick response, thanks.

Left a comment on the MR that needs a response.

Thanks @quietone. Updated.

The Needs Review Queue Bot tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

Would agree with removing $file_system->prepareDirectory($directory, FileSystemInterface::CREATE_DIRECTORY); mainly because the sentence below the example mentions copying but nothing about needing to prepare the folder, which to my knowledge isn't always needed

Removed $file_system->prepareDirectory($directory, FileSystemInterface::CREATE_DIRECTORY); from example.

Docs are updated as required.
RTBC.

I removed one blank line from the changes so this meets coding standards. And updated credit.

The changes are an improvement so if there is anything more let's put that in a followup. Leaving at RTBC.

Thanks for sorting out the credits.

Committed d135a79 and pushed to 11.x. Thanks!