Flysystem Aws S3 V3 Laravel Package

Getting Started

Install the package via Composer to enable AWS S3 integration with Flysystem:

composer require league/flysystem-aws-s3-v3

In Laravel, the most common first step is configuring a new S3 disk in config/filesystems.php using the s3 driver. The adapter auto-registers when league/flysystem-bundle or league/flysystem-aws-s3-v3 is present. Start by uploading a file:

Storage::disk('s3')->put('avatars/me.jpg', $fileContent);

For non-Laravel apps, manually instantiate the AwsS3V3Adapter with an S3Client and wrap it in a Filesystem. Check the official docs for credential options (ENV, IAM roles, config arrays).

Implementation Patterns

• Laravel Disks: Use config/filesystems.php to define custom S3 disks with environment-driven config (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET, AWS_DEFAULT_REGION). Leverage Laravel’s Storage::disk('custom-s3') for contextual logic (e.g., public assets vs. user uploads).
• Typed Flysystem Injection: Inject League\Flysystem\FilesystemOperator (or FilesystemInterface) via constructor/type-hinting—especially useful for unit tests where you swap adapters.
• Visibility Consistency: Explicitly set visibility on writes:

  $filesystem->write('private-report.pdf', $content, ['visibility' => 'private']);
  

  Combine with bucket policies to ensure public files don’t accidentally become private.
• Async Workflows: For Laravel Horizon jobs or Octane with ReactPHP, wrap the adapter using AsyncFilesystemDecorator to avoid blocking I/O:

  $asyncFs = new AsyncFilesystemDecorator($filesystem);
  $promise = $asyncFs->writeAsync('logs/app.log', $data);
  

• Testing Isolation: Mock FilesystemOperator in unit tests. For integration tests, use league/flysystem-memory or awssum/laravel-test-s3 to avoid real API calls.

Gotchas and Tips

• Path Quirks: S3 has no directories—'path' => 'uploads' + filename avatar.png yields key uploads/avatar.png. Avoid empty strings or '.' as prefix—use 'uploads/' for clarity, but never '/' (results in 'filename', not '/filename').
• Client Reuse: Always reuse the S3Client instance (e.g., via Laravel’s container or manual DI). Creating new clients per request kills performance and exhausts connections.
• ACL vs. Bucket Policy Conflicts: Even with public visibility, S3 blocks access if bucket policy denies s3:GetObject for public users. Verify bucket-level permissions in AWS Console > Permissions > Block public access.
• Path Style Endpoints: For S3-compatible services (MinIO, Wasabi), set 'url' => env('AWS_URL') and 'endpoint' => env('AWS_ENDPOINT') in config, and enable 'use_path_style_endpoint' => true in the SDK client config.
• Visibility Gotcha: Visibility::PUBLIC maps to acl: 'public-read', but S3 requires bucket policy or object ownership settings to allow this. In newer buckets with Object Ownership: Object Writer, ACLs are ignored—set visibility via bucket policies instead.
• Caching Pitfalls: S3 objects aren’t versioned automatically. For cache busting, prepend content hashes to filenames (img-abc123.jpg) or use Storage::temporaryUrl() for signed URLs.
• Dependency Conflicts: Ensure AWS SDK v3 (aws/aws-sdk-php) ≥3.260. Older SDK versions break this adapter. Run composer show aws/aws-sdk-php to verify—Lock to a known-good patch version in production if needed.