league/flysystem-aws-s3-v3

league/flysystem-aws-s3-v3 plugs Amazon S3 into league/flysystem, PHP’s abstraction layer for filesystem operations. It wraps the AWS SDK for PHP’s S3 client behind Flysystem’s FilesystemAdapter contract, so application code reads, writes, copies, moves, and lists S3 objects using the exact same API it would use for local disk, FTP, or any other Flysystem adapter.

Beyond basic CRUD, the adapter implements Flysystem’s optional capability interfaces for public URLs, presigned temporary URLs, and ETag-based checksums, and exposes AWS-specific tuning (storage class, server-side encryption, ACLs, multipart upload thresholds) through a forwarded-options array so advanced S3 behavior stays reachable without breaking the abstraction.

What You Get

• A FilesystemAdapter implementation (AwsS3V3Adapter) that plugs directly into league/flysystem’s Filesystem class
• Support for Flysystem’s PublicUrlGenerator, TemporaryUrlGenerator, and ChecksumProvider capability interfaces (public URLs, presigned URLs, ETag checksums)
• Automatic MIME type detection on upload via league/mime-type-detection, with manual override support
• A pluggable VisibilityConverter (PortableVisibilityConverter by default) mapping Flysystem’s public/private visibility model onto S3 ACLs
• Configurable forwarding of AWS-specific options (ACL, StorageClass, ServerSideEncryption, multipart thresholds) without leaving the Flysystem abstraction

Common Use Cases

• Swapping local disk storage for S3 in a Laravel, Symfony, or plain-PHP app without rewriting file-handling code
• Generating presigned temporary URLs for time-limited, authenticated access to private S3 objects
• Building multi-adapter storage layers (local + S3 + FTP) behind one consistent Flysystem API for testing and environment portability
• Streaming large file uploads/downloads to and from S3 buckets with automatic multipart upload handling

Under The Hood

Architecture - The adapter wraps AWS SDK’s S3ClientInterface behind Flysystem’s FilesystemAdapter contract. The central AwsS3V3Adapter class (526 lines) implements FilesystemAdapter plus the optional PublicUrlGenerator, ChecksumProvider, and TemporaryUrlGenerator interfaces from league/flysystem. It uses a PathPrefixer to scope all keys under an optional bucket prefix, and delegates visibility translation to a VisibilityConverter (PortableVisibilityConverter by default) that maps Flysystem’s public/private model onto S3 ACLs. Every S3 call - doesObjectExistV2, ListObjectsV2 via a paginator, DeleteObject, PutObjectAcl, GetObjectAcl, HeadObject, GetObject, upload(), copy(), deleteMatchingObjects(), and createPresignedRequest() - is delegated to the injected S3ClientInterface, keeping the adapter a thin, testable translation layer rather than a reimplementation of S3’s API. Paginated listing is exposed as a PHP Generator that flattens ListObjectsV2 pages into a single stream of CommonPrefixes and Contents entries consumed by listContents().

Tech Stack - A Composer package requiring PHP ^8.0.2, league/flysystem ^3.10.0 (the abstraction it implements), league/mime-type-detection ^1.0.0 (FinfoMimeTypeDetector for automatic Content-Type detection), and aws/aws-sdk-php ^3.371.5 (the actual S3 client). There is no build step - it’s pure PHP source, five files totaling roughly 1,260 lines, autoloaded via PSR-4 under League\Flysystem\AwsS3V3. A composer conflict entry blocks known-incompatible old guzzlehttp/ringphp and guzzlehttp/guzzle releases.

Code Quality - A single AwsS3V3AdapterTest.php (491 lines) exercises write, read, delete, copy, move, visibility, checksum, and directory-listing behavior, backed by S3ClientStub.php (184 lines), a lightweight in-memory double standing in for real AWS calls during tests. Source code uses declare(strict_types=1), typed and promoted constructor properties, and wraps every AWS SDK Throwable in a named Flysystem exception (UnableToWriteFile, UnableToReadFile, UnableToCopyFile, etc.), giving callers a consistent Flysystem-native error surface instead of leaking AWS SDK exception types.

API Design - Because it implements Flysystem’s FilesystemAdapter interface, the public surface is dictated entirely by that contract, so a developer who already knows Flysystem’s read/write/delete/copy/move/listContents API needs to learn almost nothing new. The adapter additionally implements all three of Flysystem’s optional capability interfaces, so presigned URLs and ETag checksums work through the same generic $filesystem->temporaryUrl()/checksum() calls used by every other Flysystem adapter. Advanced AWS behavior (SSE, storage class, multipart thresholds) is reachable through constructor-level forwardedOptions/multipartUploadOptions arrays rather than subclassing. Getting started requires only composer require, an S3 client instance, and a bucket name.