FileSystem::deleteRecursive() leaves files/directories when realpath() returns FALSE

Problem/Motivation

In Drupal 10.5.4, FileSystem::deleteRecursive() silently fails when used with streamWrappers return FALSE from realpath(), this is most common in remote stream wrappers (S3fs, Azure, Flysystem, etc.) however local streams where the raw file is not intended to be directly accessed (compression, encryption, etc) will encounter the same. The method returns TRUE indicating success, but no files are actually deleted from storage.

This breaks critical functionality like image style flushing (drush image-flush) when using remote file systems, causing stale derivatives to remain in storage indefinitely.

This additionally presents a risk of sensitive data being left on disk.

Steps to reproduce

1. Install Drupal 10.5.4 with S3fs module (or any remote stream wrapper)
2. Configure S3fs to handle public:// files
3. Generate some image style derivatives
4. Run drush image-flush <style_name>
5. Check the S3 bucket - files still exist
6. Check s3fs_file table - metadata records still exist

Expected behavior

deleteRecursive() should delete all files and directories from remote storage, just as it does with local filesystems.

Actual behavior

deleteRecursive() returns TRUE but deletes nothing. Files remain in S3 and metadata remains in the database.

Root cause

In Drupal 10.5.x, FileSystem::deleteRecursive() was changed to call realpath() at the beginning:

public function deleteRecursive($path, ?callable $callback = NULL) {
    // Ensure paths are local paths when a recursive delete is started.
    if ($this->streamWrapperManager->isValidUri($path)) {
      $path = $this->realpath($path);  // ← Returns FALSE for remote URIs
    }
    
    if ($callback) {
      call_user_func($callback, $path);
    }
    
    // Allow broken links to be removed.
    if (!file_exists($path) && !is_link($path)) {  // ← file_exists(FALSE) = FALSE
      return TRUE;  // ← Returns here without doing anything!
    }
    // ... rest of method
}

The issue:

1. Remote stream wrappers correctly return FALSE from realpath() (as documented in FileSystemInterface::realpath(): "does not work for remote URIs")
2. $path becomes FALSE
3. file_exists(FALSE) returns FALSE
4. Method hits the early return and exits without deleting anything
5. Returns TRUE claiming success

Verification code

// Test realpath with S3
$wrapper = \Drupal::service('stream_wrapper_manager')->getViaUri('public://styles/medium');
$realpath = $wrapper->realpath();
var_dump($realpath); // bool(false)

// Test deleteRecursive
$file_system = \Drupal::service('file_system');
$result = $file_system->deleteRecursive('public://styles/medium');
var_dump($result); // bool(true) - claims success

// But files still exist
var_dump(is_dir('public://styles/medium')); // bool(true) - still there!

Workaround

Delete files individually without using deleteRecursive():

function manualFlush($uri) {
  $database = \Drupal::database();
  
  // Get all URIs from metadata
  $uris = $database->select('s3fs_file', 'f')
    ->fields('f', ['uri'])
    ->condition('uri', $uri . '%', 'LIKE')
    ->execute()
    ->fetchCol();
  
  // Delete each file individually
  foreach ($uris as $file_uri) {
    if (file_exists($file_uri)) {
      unlink($file_uri);  // This works!
    }
  }
  
  // Clean up metadata
  $database->delete('s3fs_file')
    ->condition('uri', $uri . '%', 'LIKE')
    ->execute();
}

Proposed resolution

Remove the realpath() conversion from deleteRecursive(). Stream wrapper URIs should be used directly, just like all other file operations (copy(), move(), delete(), etc.) already do.

The method should work with stream wrapper URIs throughout, not attempt to convert them to local paths.

API changes

None - this is a bug fix restoring previous behavior.

Affected versions

Drupal 10.5.x (possibly 10.4.x - needs verification)

Related issues

• Similar realpath() issue fixed in EXIF Orientation module: #3284307
• S3fs image URL generation issues when derivatives don't exist: Various reports in S3fs queue
• Views Data Export with S3fs: #3325431

Impact

This affects any site using remote stream wrappers for file storage, breaking:

• Image style flushing
• Any code using deleteRecursive() on remote URIs
• Proper cache management for derivative files

This is a regression that breaks a core Drupal feature (image styles) when using remote file systems, which is increasingly common in cloud deployments.