AWS S3 Driver

Purpose and Scope

The AWS S3 Driver provides integration with Amazon S3 and S3-compatible storage services through the AwsS3V3Adapter class. This adapter extends the base FilesystemAdapter to add S3-specific functionality including pre-signed URL generation, custom endpoint configuration, and temporary upload URLs.

This page focuses on the S3 driver implementation details, configuration options, and S3-specific features. For information about the base adapter functionality shared across all drivers, see Driver Architecture and FilesystemAdapter. For details on connection pooling behavior with S3, see Object Pooling for Cloud Drivers. For general URL generation concepts across all drivers, see URL Generation.

Sources: src/AwsS3V3Adapter.php1-125

---

Class Structure and Dependencies

The AwsS3V3Adapter class extends FilesystemAdapter and implements the Cloud interface, providing full S3 integration capabilities.

Key Components

Component	Type	Purpose
AwsS3V3Adapter	Class	Main adapter implementation for S3 operations
S3Client	AWS SDK	Underlying AWS S3 client for API operations
S3Adapter	Flysystem	League Flysystem's S3 adapter implementation
Conditionable	Trait	Provides conditional method execution capabilities

The adapter receives all dependencies through constructor injection src/AwsS3V3Adapter.php26-31:

Parameters:
- FilesystemOperator $driver: The Flysystem operator instance
- S3Adapter $adapter: The Flysystem S3 adapter
- array $config: Driver configuration array
- S3Client $client: AWS S3 client instance

Sources: src/AwsS3V3Adapter.php14-31

---

Configuration

The S3 driver is configured in the filesystem configuration file under a disk definition with driver set to s3.

Required Configuration Options

Option	Environment Variable	Description
key	AWS_ACCESS_KEY_ID	AWS access key ID for authentication
secret	AWS_SECRET_ACCESS_KEY	AWS secret access key for authentication
region	AWS_DEFAULT_REGION	AWS region (e.g., us-east-1, eu-west-1)
bucket	AWS_BUCKET	S3 bucket name

Optional Configuration Options

Option	Environment Variable	Default	Description
url	AWS_URL	null	Custom base URL for public URLs
endpoint	AWS_ENDPOINT	null	Custom S3 endpoint (for S3-compatible services)
use_path_style_endpoint	AWS_USE_PATH_STYLE_ENDPOINT	false	Use path-style URLs instead of virtual-hosted-style
temporary_url	-	null	Custom base URL for pre-signed URLs
throw	-	false	Whether to throw exceptions on errors

Pool Configuration

The S3 driver supports connection pooling to improve performance in concurrent environments:

Pool Option	Default	Description
min_objects	1	Minimum number of pooled connections
max_objects	10	Maximum number of pooled connections
wait_timeout	3.0	Seconds to wait for available connection
max_lifetime	60.0	Maximum connection lifetime in seconds

Example Configuration

publish/filesystems.php47-63

Sources: publish/filesystems.php47-63

---

URL Generation

The AwsS3V3Adapter provides multiple methods for generating URLs to S3 objects, supporting both public access and temporary authenticated access.

Public URLs

The url() method generates a public URL for an object in the S3 bucket src/AwsS3V3Adapter.php38-51

Behavior:

1. If config['url'] is set, uses the custom base URL concatenated with the prefixed path
2. Otherwise, calls S3Client::getObjectUrl() to generate the default S3 URL

URL Format Examples:

• Default: https://bucket-name.s3.region.amazonaws.com/path/to/file.txt
• Custom URL: https://cdn.example.com/path/to/file.txt
• With prefix: https://bucket-name.s3.region.amazonaws.com/prefix/path/to/file.txt

Sources: src/AwsS3V3Adapter.php38-51

Temporary Download URLs

The temporaryUrl() method generates a pre-signed URL that grants temporary access to download a private object src/AwsS3V3Adapter.php64-85

Method Signature:

Process Flow:

Parameters:

Parameter	Type	Description
$path	string	Path to the file in the bucket
$expiration	DateTimeInterface	URL expiration time
$options	array	Additional S3 GetObject parameters

Additional Options:

The $options array is merged with the GetObject command parameters, allowing customization such as:

• ResponseContentDisposition: Force download with specific filename
• ResponseContentType: Override content type
• VersionId: Access specific object version

Custom Base URL:

If config['temporary_url'] is set, the adapter replaces the base URL of the generated pre-signed URL while preserving query parameters and signature src/AwsS3V3Adapter.php80-82

Sources: src/AwsS3V3Adapter.php64-85

Temporary Upload URLs

The temporaryUploadUrl() method generates a pre-signed URL that allows clients to upload directly to S3 without exposing AWS credentials src/AwsS3V3Adapter.php90-116

Method Signature:

Return Value:

Returns an array containing:

Process:

1. Creates a PutObject command with the bucket, key, and additional options
2. Generates a pre-signed request with the specified expiration
3. Optionally replaces the base URL if config['temporary_url'] is set
4. Returns both the URL and required headers for the upload request

Client-Side Usage:

The returned headers must be included in the HTTP PUT request to successfully upload the file. The URL signature validates both the URL and the headers.

Sources: src/AwsS3V3Adapter.php90-116

---

S3-Specific Features

Path Prefixing

All methods automatically apply path prefixing through the inherited PathPrefixer instance. The path prefix is configured during driver instantiation and transparently prepended to all object keys.

Example:

Configuration: path_prefix = "uploads/"
Application path: "documents/file.pdf"
Actual S3 key: "uploads/documents/file.pdf"

The prefixer is accessed via $this->prefixer->prefixPath($path) throughout the adapter src/AwsS3V3Adapter.php44-94

Custom Endpoints

The endpoint configuration option enables use of S3-compatible services like MinIO, DigitalOcean Spaces, or Wasabi:

Path-style endpoints use the format https://endpoint/bucket/key instead of https://bucket.endpoint/key.

S3 Client Access

Applications can access the underlying S3 client directly for advanced operations not exposed by the filesystem interface src/AwsS3V3Adapter.php121-124:

This allows executing arbitrary S3 operations such as:

• Bucket management
• Object ACL manipulation
• Multipart uploads
• Bucket policies and CORS configuration

Sources: src/AwsS3V3Adapter.php121-124

---

Integration with Object Pooling

The S3 driver is marked as poolable in the FilesystemManager, meaning it supports connection pooling when configured with pool options.

Pooling Behavior

When pool configuration is present:

1. Pool Creation: FilesystemManager wraps the S3 adapter creator in a FilesystemPoolProxy
2. Instance Management: Pool maintains min/max connections as configured
3. Request Handling: Each operation borrows an adapter, executes the method, and returns it to the pool
4. Lifecycle: Adapters respect max_lifetime and are recreated as needed

Benefits for S3

Connection pooling provides significant performance improvements for S3:

• Reduced Overhead: Reuses HTTP connections to S3 endpoints
• Concurrent Requests: Multiple coroutines can efficiently share adapter instances
• Resource Control: Limits maximum simultaneous S3 connections
• Connection Warming: Maintains minimum ready connections

For detailed pooling mechanics, see Object Pooling for Cloud Drivers.

Sources: publish/filesystems.php57-62

---

URL Capability Matrix

The S3 driver supports all URL generation capabilities:

Method	Supported	Notes
url()	✓	Public URLs with optional custom base URL
temporaryUrl()	✓	Pre-signed download URLs with expiration
temporaryUploadUrl()	✓	Pre-signed upload URLs with headers
providesTemporaryUrls()	✓	Always returns true

Custom URL Configuration:

Configuration Key	Purpose	Applied To
config['url']	Base URL for public access	url() method
config['temporary_url']	Base URL for pre-signed URLs	temporaryUrl() and temporaryUploadUrl()

Sources: src/AwsS3V3Adapter.php38-116