Flysystem Async Aws S3 Laravel Package

Getting Started

Install the package via Composer:

composer require league/flysystem-async-aws-s3  

Then, create an AsyncAws\S3\S3Client instance (using AsyncAws directly) and wrap it with Flysystem’s adapter:

use AsyncAws\S3\S3Client;  
use League\Flysystem\AsyncAwsS3\AsyncAwsS3Adapter;  
use League\Flysystem\Filesystem;  

$s3Client = new S3Client([  
    'endpoint' => 'https://s3.amazonaws.com',  
    'region' => 'us-east-1',  
    'credentials' => [  
        'key' => 'your-key',  
        'secret' => 'your-secret',  
    ],  
]);  

$adapter = new AsyncAwsS3Adapter($s3Client, 'your-bucket-name');  
$filesystem = new Filesystem($adapter);  

Start by testing basic operations like write(), read(), and has() to confirm connectivity.

Implementation Patterns

• Laravel Integration: Register a custom Flysystem disk in config/filesystems.php by extending the S3 driver and injecting the AsyncAwsS3Adapter manually, since this adapter is not included in Laravel’s core S3 driver. Use a custom service provider to wire S3Client → AsyncAwsS3Adapter → Filesystem.
• Async Operations: Leverage AsyncAws’ non-blocking HTTP client for high-throughput uploads/downloads (e.g., batch image processing). Wrap Flysystem calls with ParallelAsyncExecutor or custom concurrency logic.
• Stream Handling: Use readStream()/writeStream() for large files—AsyncAws streams data efficiently without loading into memory.
• Middleware Layer: Add Flysystem middleware (e.g., ChecksumValidationMiddleware) to ensure integrity for critical uploads, especially when syncing to other stores.

Gotchas and Tips

• No Laravel Out-of-the-Box Support: Laravel’s league/flysystem-aws-s3-v3 is widely used, but this package requires manual adapter wiring—no built-in aws-s3-async driver.
• AsyncAws Auth Quirks: Ensure credentials are explicitly set; environment variables or instance roles may not auto-resolve depending on AsyncAws version and configuration. Test with aws s3api head-bucket parity.
• Metadata Handling: AsyncAws sends S3 object metadata only on HeadObject or GetObject, not ListObjects. Use ->listContents()->map(fn ($file) => $filesystem->getVisibility($file['path'])) to enrich listing with visibility info if needed.
• Maturity Warning: As a sub-split with low stars/dependents, verify compatibility with your AsyncAws and Flysystem versions. Pin versions tightly in CI.
• Error Parsing: AsyncAws exceptions (e.g., S3Exception) expose raw HTTP details—catch AwsException and log getStatusCode()/getErrorCode() for actionable debugging.