[12.x] Add processFileUsing() method to AwsS3V3Adapter for temporary local processing of remote files and get() and path() overrides

[hmennen90]

Description

This PR adds a new processFileUsing() method to the AwsS3V3Adapter that enables safe and temporary local processing of remote files (for example, ZIP archives) stored on S3 or any S3-compatible storage system.

When working with tools like PHP’s ZipArchive, a local file path is required — however, S3 streams cannot be passed directly.
The new processFileUsing() method provides a clean and framework-integrated solution to handle this scenario efficiently.

In addition, the S3 adapter now provides ZIP-aware overrides for get() and path() so that ZIP files stored on S3 can be transparently copied to local storage before being read or used with APIs that expect a local filesystem path.

---

How it works

processFileUsing()

• If the given file path ends with .zip, the adapter:

  1. Reads the file stream from S3.
  2. Writes it temporarily to the local disk.
  3. Passes the local file path to the provided callback.
  4. Deletes the temporary file after the callback finishes (even if an exception occurs).

• For all other file types, the callback simply receives the original path.

This pattern allows developers to work with real local files when necessary, while automatically cleaning up any temporary data.

ZIP handling for get() and path() on S3

• When calling get() for a path ending in .zip on the S3 adapter:

  • The file is streamed from S3 and written to local storage.
  • get() then returns the contents of the local copy instead of reading directly from S3.

• When calling path() for a path ending in .zip on the S3 adapter:

  • The file is likewise streamed from S3 and mirrored to local storage.
  • path() returns a path that can be used with APIs (such as ZipArchive) that require a local filesystem path.

For non-ZIP files, both get() and path() keep their existing behavior and delegate to the parent implementation.

---

Example usage

// Processing a ZIP file using a local path
Storage::disk('s3')->getAdapter()->processFileUsing('releases/package.zip', function (string $localPath) {
    $zip = new ZipArchive();
    if ($zip->open($localPath) === true) {
        for ($i = 0; $i < $zip->numFiles; $i++) {
            Log::info($zip->getNameIndex($i));
        }
        $zip->close();
    }
});

// Reading a ZIP file via get() – content is served from a local copy
$contents = Storage::disk('s3')->get('releases/package.zip');

// Obtaining a filesystem path for a ZIP file – path points to the local copy
$localPath = Storage::disk('s3')->path('releases/package.zip');

// The returned $localPath can safely be used with ZipArchive::open()
$zip = new ZipArchive();
if ($zip->open($localPath) === true) {
    // …
    $zip->close();
}