Simple S3 Laravel Package

Getting Started

Install via composer require async-aws/simple-s3. After installation, instantiate the client—credentials load automatically from environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION) or pass them explicitly. The first practical use is uploading content:

use AsyncAws\SimpleS3\SimpleS3Client;

$client = new SimpleS3Client();
$client->upload('my-bucket', 'documents/report.pdf', fopen('/path/report.pdf', 'r'));

Review the integration guide for configuration depth (e.g., custom endpoints, regional overrides).

Implementation Patterns

• Direct S3 I/O: Replace verbose SDK code with terse methods: upload(), download(), delete(), and has()—ideal for controllers, jobs, or console commands handling user uploads or backups.
• Presigned URLs for Client-Side Transfers: Generate secure, expiring URLs for browser-to-S3 direct uploads/downloads:

  $url = $client->getPresignedUrl('my-bucket', 'uploads/avatar.png', '+20 minutes', $versionId: $versionId);
  

• Bulk Operations with Async Efficiency: Use upload() in loops backed by AsyncAws\Core\Operation\ParallelExecutor for concurrent uploads without blocking the main thread—ideal for media processing pipelines.
• Laravel Integration: Bind as a shared service in AppServiceProvider:

  $this->app->singleton(\AsyncAws\SimpleS3\SimpleS3Client::class);
  

  Then inject into services needing stateless, async S3 access without tight coupling to filesystem abstractions.
• Fallback for Advanced Features: When needing non-standard operations (e.g., lifecycle rules, multipart uploads), access the underlying S3Client via $client->getS3Client().

Gotchas and Tips

• Strict PHP 8.2+ Requirement: Version 3.x requires PHP 8.2+—verify runtime before deploying; downgrade to 2.x only if legacy environments persist.
• Versioning Buckets Demand Explicit versionId: If S3 versioning is enabled, always pass versionId in getPresignedUrl() or download()—otherwise, requests default to latest version, potentially causing stale data exposure.
• No Built-in Retry or Circuit Breaking: Unlike AWS SDK v2/v3, this thin wrapper omits automatic retries—wrap critical calls in custom retry logic (e.g., while ($retries++ < 3) { ... } catch (RuntimeException $e) { ... }).
• Type Safety Improvements Enhance DX: PHP 8.1+ features like union types (string|resource|\Traversable) and refined docblocks improve IDE support and static analysis—leverage PHPStan/Psalm rules for validation.
• Avoid Unnecessary Abstraction for ACLs/Metadata: This package does not expose object ACLs, metadata, or tagging—fall back to the raw S3Client for such needs to avoid fragile workarounds.
• Test in Isolation: Unit-testS3 interactions directly against SimpleS3Client mocks—no need for real buckets or filesystem fakes unless layering on Laravel’s Storage abstraction.