Issue #2843100 by VladimirAus, quietone, immaculatexavier, yogeshmpawar,...

   *

   * 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 $fileExists parameter.

   * - If the $source and $destination are equal, the behavior depends on the

   *   $fileExists parameter.

   * - If $source and $destination are valid and readable/writable, then only

   *   perform the copy operation.

   * - If $source and $destination are equal then a FileException exception is

   *   thrown.

   * - If the $destination file already exists, the behavior depends on the

   *   $fileExists parameter as follows `FileExists::Error` will error out,

   *   `FileExists::Replace` will replace the existing file, and

   *   `FileExists::Rename` will assign a new unique name.

   * - Provides a fallback using realpaths if the move fails using stream

   *   wrappers. This can occur because PHP's copy() function does not properly

   *   support streams if open_basedir is enabled. See

   *   https://bugs.php.net/bug.php?id=60456

   *   support streams if open_basedir is enabled.

   *

   * Example:

   * @code

   * use Drupal\Core\File\FileExists;

   * use Drupal\Core\File\FileSystemInterface;

   * ...

   * $directory = 'public://example-dir';

   * $file_system = \Drupal::service('file_system');

   * $file_system->copy($filepath, $directory . '/' . basename($filepath), FileExists::Replace);

   * @endcode

   * In this example, file is copied from $filepath and is replaced at the

   * destination if exists.

   *

   * @param string $source

   *   A string specifying the filepath or URI of the source file.

   * @throws \ValueError

   *   Thrown if $fileExists is a legacy int and not a valid value.

   *

   * @see \Drupal\Core\File\FileSystemInterface::createFilename()

   * @see https://bugs.php.net/bug.php?id=60456

   */

  public function move($source, $destination, /* FileExists */$fileExists = FileExists::Rename);