AsyncAws S3 Client

https://github.com/async-aws/s3
Admin
An API client for Amazon S3 that provides async/await support for S3 operations in PHP applications.
Tokens:88,623
Snippets:424
Trust Score:7.4
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Example output class declaration

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Result-output-classes.md

Shows the base structure of an output class extending AsyncAws\Core\Result. This is an illustrative example, not final code.

```php
class PutObjectOutput extends Result   // example; not final
```

--------------------------------

### Install AsyncAws S3 Client with Composer

Source: https://github.com/async-aws/s3/blob/master/README.md

Use this command to install the AsyncAws S3 client via Composer. Run it in your project directory.

```cli
composer require async-aws/s3
```

--------------------------------

### Create multipart upload usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-multipart-operations.md

Example of calling createMultipartUpload with Bucket and Key, then retrieving the upload ID. The upload ID is required for all subsequent part requests.

```php
$init = $s3->createMultipartUpload(['Bucket' => 'my-bucket', 'Key' => 'large.bin']);
$uploadId = $init->getUploadId();
```

--------------------------------

### uploadPart usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-multipart-operations.md

Example of calling uploadPart to upload a part and storing the ETag in an array for later use in completeMultipartUpload.

```php
$part = $s3->uploadPart([
    'Bucket' => 'my-bucket',
    'Key' => 'large.bin',
    'UploadId' => $uploadId,
    'PartNumber' => 1,
    'Body' => $chunkData,
])->resolve();
$parts[] = ['PartNumber' => 1, 'ETag' => $part->getEtag()];
```

--------------------------------

### getObject usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-object-operations.md

Example of calling getObject with Bucket, Key, and Range parameters, and retrieving the content as a string using the ResultStream API.

```php
$result = $s3->getObject(['Bucket' => 'my-bucket', 'Key' => 'photos/sunset.jpg', 'Range' => 'bytes=0-1024']);
$content = $result->getBody()->getContentAsString(); // ResultStream API
```

--------------------------------

### Complete multipart upload example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-multipart-operations.md

Example of completing a multipart upload by providing the bucket, key, upload ID, and the list of parts. The result is resolved and the object location and ETag are printed.

```php
$completed = $s3->completeMultipartUpload([
    'Bucket' => 'my-bucket',
    'Key' => 'large.bin',
    'UploadId' => $uploadId,
    'MultipartUpload' => ['Parts' => $parts],   // [['PartNumber'=>n,'ETag'=>e],...]
])->resolve();

printf("object at %s, etag=%s\n", $completed->getLocation(), $completed->getEtag());
```

--------------------------------

### putBucketVersioning method signature and usage

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-bucket-operations.md

Method signature and usage example for enabling bucket versioning. The input requires a Bucket and a VersioningConfiguration array with 'Status' set to BucketVersioningStatus::ENABLED or SUSPENDED. The example calls putBucketVersioning on an S3 client and resolves the result.

```php
/**
 * @param array{
 *   Bucket: string,
 *   ContentMD5?: string|null,
 *   ChecksumAlgorithm?: ChecksumAlgorithm::*|null,
 *   MFA?: string|null,
 *   VersioningConfiguration: VersioningConfiguration|array,
 *   ExpectedBucketOwner?: string|null,
 *   '@region'?: string|null,
 * }|PutBucketVersioningRequest $input
 */
public function putBucketVersioning($input): Result
```

```php
$s3->putBucketVersioning([
    'Bucket' => 'my-bucket',
    'VersioningConfiguration' => ['Status' => BucketVersioningStatus::ENABLED],
])->resolve();
```

--------------------------------

### headObject usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-object-operations.md

Example of calling headObject to retrieve metadata for an object and printing its size and last modified date.

```php
$meta = $s3->headObject(['Bucket' => 'my-bucket', 'Key' => 'photos/sunset.jpg']);
printf("size=%d modified=%s\n", $meta->getContentLength(), $meta->getLastModified()->format('c'));
```

--------------------------------

### copyObject usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-object-operations.md

Example of copying an object from a source bucket to a destination bucket, replacing metadata with a custom 'copied' key. The result's ETag is printed.

```php
$out = $s3->copyObject([
    'Bucket' => 'dest-bucket',
    'Key' => 'backup/file.txt',
    'CopySource' => '/source-bucket/dir/file.txt',
    'MetadataDirective' => MetadataDirective::REPLACE,
    'Metadata' => ['copied' => 'true'],
]);
echo $out->getCopyObjectResult()->getEtag();
```

--------------------------------

### listParts usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-multipart-operations.md

Iterates over parts of a multipart upload, printing each part number and size.

```php
foreach ($s3->listParts(['Bucket' => 'my-bucket', 'Key' => 'large.bin', 'UploadId' => $uploadId]) as $part) {
    echo $part->getPartNumber() . ' @ ' . $part->getSize() . "\n";
}
```

--------------------------------

### PutObjectRequest usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Input-request-classes.md

Shows how to create a PutObjectRequest instance with required Bucket and Key, set body, content type, storage class, and metadata, then pass it to the client's putObject method.

```php
use AsyncAws\S3\Input\PutObjectRequest;
use AsyncAws\S3\Enum\StorageClass;

$input = (new PutObjectRequest(['Bucket' => 'my-bucket', 'Key' => 'obj.txt']))
    ->setBody('hello')
    ->setContentType('text/plain')
    ->setStorageClass(StorageClass::STANDARD_IA)
    ->setMetadata(['app' => 'demo']);

$result = $s3->putObject($input); // client accepts the Input instance too
```

--------------------------------

### S3Client usage example with asynchronous putObject

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client.md

Demonstrates creating an S3Client with region and pathStyleEndpoint options, then issuing multiple putObject requests asynchronously. The getEtag() method resolves the response lazily, and resolve() completes each request. This example shows how to batch operations before resolving results.

```php
use AsyncAws\S3\S3Client;

$s3 = new S3Client([
    'region' => 'us-west-2',
    'pathStyleEndpoint' => false,
]);

$result = $s3->putObject(['Bucket' => 'my-bucket', 'Key' => 'dir/file.txt', 'Body' => 'content']);
$etag = $result->getEtag(); // resolves the response lazily

// Operations are asynchronous: multiple requests can be issued before resolving
$results = [];
foreach (['a.txt', 'b.txt', 'c.txt'] as $key) {
    $results[$key] = $s3->putObject(['Bucket' => 'my-bucket', 'Key' => $key, 'Body' => $key]);
}
foreach ($results as $key => $result) {
    $result->resolve(); // completes the request
}
```

--------------------------------

### putObject example with metadata and encryption

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-object-operations.md

Shows a typical putObject call that uploads a file from a local path, sets content type and metadata, enables SSE-KMS encryption, and uses the INTELLIGENT_TIERING storage class. The result's ETag is printed.

```php
$result = $s3->putObject([
    'Bucket' => 'my-bucket',
    'Key' => 'photos/sunset.jpg',
    'Body' => fopen('/tmp/sunset.jpg', 'r'),
    'ContentType' => 'image/jpeg',
    'Metadata' => ['photographer' => 'jane'],
    'ServerSideEncryption' => ServerSideEncryption::AWS_KMS,
    'StorageClass' => StorageClass::INTELLIGENT_TIERING,
]);
echo $result->getEtag();
```

--------------------------------

### putObjectTagging usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-object-operations.md

Example of calling putObjectTagging with an array input to set a tag on an object. Uses 'my-bucket' and 'photos/sunset.jpg' with a single tag.

```php
$s3->putObjectTagging([
    'Bucket' => 'my-bucket',
    'Key' => 'photos/sunset.jpg',
    'Tagging' => ['TagSet' => [['Key' => 'project', 'Value' => 'hiking']]],
])->resolve();
```

--------------------------------

### listObjectsV2 usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-multipart-operations.md

Iterates over objects returned by listObjectsV2 for a given bucket and prefix, printing each object's key and size.

```php
foreach ($s3->listObjectsV2(['Bucket' => 'my-bucket', 'Prefix' => 'photos/']) as $object) {
    echo $object->getKey() . ' ' . $object->getSize() . "\n";
}
```

--------------------------------

### putBucketCors method signature and usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-bucket-operations.md

Sets the CORS configuration for a bucket. The CORSConfiguration parameter is required and can be a ValueObject\CORSConfiguration or an array with 'CORSRules'. The example shows a minimal configuration with allowed methods, origins, headers, and max age. Returns a plain Result.

```php
/**
 * @param array{
 *   Bucket: string,
 *   CORSConfiguration: CORSConfiguration|array,
 *   ContentMD5?: string|null,
 *   ChecksumAlgorithm?: ChecksumAlgorithm::*|null,
 *   ExpectedBucketOwner?: string|null,
 *   '@region'?: string|null,
 * }|PutBucketCorsRequest $input
 */
public function putBucketCors($input): Result
```

```php
$s3->putBucketCors([
    'Bucket' => 'my-bucket',
    'CORSConfiguration' => [
        'CORSRules' => [[
            'AllowedMethods' => ['GET', 'PUT'],
            'AllowedOrigins' => ['https://app.example.com'],
            'AllowedHeaders' => ['*'],
            'MaxAgeSeconds' => 3000,
        ]],
    ],
])->resolve();
```

--------------------------------

### ListBucketsRequest class template

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Input-request-classes.md

Example of the common class shape for all 35 input classes, using ListBucketsRequest as an example. It shows properties, constructor, create() method, getters, request() method, and fluent setters.

```php
final class ListBucketsRequest extends Input
{
    private $maxBuckets;         // @var int|null
    private $continuationToken;  // @var string|null
    private $prefix;             // @var string|null
    private $bucketRegion;       // @var string|null

    /**
     * @param array{
     *   MaxBuckets?: int|null,
     *   ContinuationToken?: string|null,
     *   Prefix?: string|null,
     *   BucketRegion?: string|null,
     *   '@region'?: string|null,
     * } $input
     */
    public function __construct(array $input = [])
    // assigns $input[key] ?? null per property; '@region' consumed by parent::__construct()

    public static function create($input): self
    // $input instanceof self ? $input : new self($input)

    public function getBucketRegion(): ?string          // one getter per property
    public function getContinuationToken(): ?string
    public function getMaxBuckets(): ?int
    public function getPrefix(): ?string

    /** @internal */
    public function request(): Request                  // builds headers/query/URI/body
    // throws AsyncAws\Core\Exception\InvalidArgument for missing required fields
    // or invalid enum values (Enum::exists() check)

    public function setBucketRegion(?string $value): self   // fluent setters return $this
    public function setContinuationToken(?string $value): self
    public function setMaxBuckets(?int $value): self
    public function setPrefix(?string $value): self
}
```

--------------------------------

### GET /{Bucket}?versions

Source: https://github.com/async-aws/s3/blob/master/_autodocs/endpoints.md

Lists object versions in a bucket. Supports pagination via key-marker and version-id-marker.

```APIDOC
## GET /{Bucket}?versions

### Description
Lists object versions in a bucket.

### Method
GET

### Endpoint
/{Bucket}?versions

### Parameters
#### Path Parameters
- **Bucket** (string) - Required - Name of the bucket.

#### Query Parameters
- **delimiter** (string) - Optional - A delimiter to group keys.
- **encoding-type** (string) - Optional - Encoding type for keys.
- **key-marker** (string) - Optional - Key to start listing from.
- **max-keys** (string) - Optional - Maximum number of keys to return.
- **prefix** (string) - Optional - Limits response to keys with the specified prefix.
- **version-id-marker** (string) - Optional - Version ID to start listing from.

### Response
#### Success Response (200)
- **Versions** (array) - List of object versions.
- **NextKeyMarker** (string) - Next key marker for pagination.
- **NextVersionIdMarker** (string) - Next version ID marker for pagination.

#### Response Example
{
  "Versions": [
    {
      "Key": "file.txt",
      "VersionId": "version-id"
    }
  ],
  "NextKeyMarker": "next-key",
  "NextVersionIdMarker": "next-version-id"
}
```

--------------------------------

### putPublicAccessBlock usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-bucket-operations.md

Example call to putPublicAccessBlock that enables all four public access block settings on the specified bucket. The resolve() method is used to wait for the operation to complete.

```php
$s3->putPublicAccessBlock([
    'Bucket' => 'my-bucket',
    'PublicAccessBlockConfiguration' => [
        'BlockPublicAcls' => true,
        'IgnorePublicAcls' => true,
        'BlockPublicPolicy' => true,
        'RestrictPublicBuckets' => true,
    ],
])->resolve();
```

--------------------------------

### abortMultipartUpload usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-multipart-operations.md

Example of calling abortMultipartUpload with an array input and catching NoSuchUploadException. The exception is thrown when the upload has already been completed or aborted.

```php
use AsyncAws\S3\Exception\NoSuchUploadException;

try {
    $s3->abortMultipartUpload(['Bucket' => 'my-bucket', 'Key' => 'large.bin', 'UploadId' => $uploadId])->resolve();
} catch (NoSuchUploadException $e) {
    // upload already completed/aborted — nothing left to free
}
```

--------------------------------

### Construct S3Client with region, pathStyleEndpoint, sendChunkedBody, and custom endpoint

Source: https://github.com/async-aws/s3/blob/master/_autodocs/configuration.md

Complete construction example for the AsyncAws S3 client. Sets region, disables path-style endpoint, enables aws-chunked streaming for large bodies, and optionally sets a custom endpoint for S3-compatible services. Credentials are provided via CredentialProvider::fromCredentials, with a comment noting the default chain as an alternative.

```php
use AsyncAws\Core\Credentials\CredentialProvider;
use AsyncAws\S3\S3Client;

$s3 = new S3Client(
    [
        'region'            => 'eu-west-2',
        'pathStyleEndpoint' => false,
        'sendChunkedBody'   => true,       // aws-chunked streaming for large bodies
        // 'endpoint'      => 'https://s3.custom.example.com',  // S3-compatible service
    ],
    CredentialProvider::fromCredentials(new Credentials('key', 'secret')) // or default chain
);
```

--------------------------------

### GET /{Bucket}?uploads

Source: https://github.com/async-aws/s3/blob/master/_autodocs/endpoints.md

Lists in-progress multipart uploads for a bucket. Supports pagination via key-marker and upload-id-marker.

```APIDOC
## GET /{Bucket}?uploads

### Description
Lists in-progress multipart uploads for a bucket.

### Method
GET

### Endpoint
/{Bucket}?uploads

### Parameters
#### Path Parameters
- **Bucket** (string) - Required - Name of the bucket.

#### Query Parameters
- **delimiter** (string) - Optional - A delimiter to group keys.
- **encoding-type** (string) - Optional - Encoding type for keys.
- **key-marker** (string) - Optional - Key to start listing from.
- **max-uploads** (string) - Optional - Maximum number of uploads to return.
- **prefix** (string) - Optional - Limits response to keys with the specified prefix.
- **upload-id-marker** (string) - Optional - Upload ID to start listing from.

### Response
#### Success Response (200)
- **Uploads** (array) - List of multipart uploads.
- **NextKeyMarker** (string) - Next key marker for pagination.
- **NextUploadIdMarker** (string) - Next upload ID marker for pagination.

#### Response Example
{
  "Uploads": [
    {
      "Key": "file.txt",
      "UploadId": "upload-id"
    }
  ],
  "NextKeyMarker": "next-key",
  "NextUploadIdMarker": "next-upload-id"
}
```

--------------------------------

### GET /

Source: https://github.com/async-aws/s3/blob/master/_autodocs/endpoints.md

Lists all buckets owned by the authenticated sender. Supports query parameters for pagination and filtering.

```APIDOC
## GET /

### Description
Lists all buckets owned by the authenticated sender.

### Method
GET

### Endpoint
/

### Parameters
#### Query Parameters
- **max-buckets** (string) - Optional - Maximum number of buckets to return.
- **continuation-token** (string) - Optional - Token to continue a previous list request.
- **prefix** (string) - Optional - Limits response to bucket names beginning with the specified prefix.
- **bucket-region** (string) - Optional - Limits response to buckets in the specified region.

### Response
#### Success Response (200)
- **Buckets** (array) - List of buckets.
- **Owner** (object) - Owner information.
- **ContinuationToken** (string) - Token for next page.

#### Response Example
{
  "Buckets": [
    {
      "Name": "example-bucket",
      "CreationDate": "2023-01-01T00:00:00Z"
    }
  ],
  "Owner": {
    "DisplayName": "owner",
    "ID": "owner-id"
  },
  "ContinuationToken": "token"
}
```

--------------------------------

### GET /{Bucket}?versioning

Source: https://github.com/async-aws/s3/blob/master/_autodocs/endpoints.md

Retrieves the versioning state of a bucket.

```APIDOC
## GET /{Bucket}?versioning

### Description
Retrieves the versioning state of a bucket.

### Method
GET

### Endpoint
/{Bucket}?versioning

### Parameters
#### Path Parameters
- **Bucket** (string) - Required - Name of the bucket.

### Response
#### Success Response (200)
- **Status** (string) - Versioning status (Enabled, Suspended).

#### Response Example
{
  "Status": "Enabled"
}
```

--------------------------------

### ListBucketsRequest

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Input-request-classes.md

Example of the common class shape for all S3 Input request classes, demonstrating constructor, create() helper, getters, setters, and request() method.

```APIDOC
## ListBucketsRequest

### Description
Represents the input for the ListBuckets S3 operation. Holds optional parameters for listing buckets and serializes them into an AsyncAws Core Request.

### Constructor
`__construct(array $input = [])`

Accepts an optional array with keys:
- `MaxBuckets` (int|null) - Optional - Maximum number of buckets to return.
- `ContinuationToken` (string|null) - Optional - Token to continue a previous listing.
- `Prefix` (string|null) - Optional - Limits response to buckets with the specified prefix.
- `BucketRegion` (string|null) - Optional - Limits response to buckets in the specified region.
- `'@region'` (string|null) - Optional - AWS region for the request, consumed by parent constructor.

### Static Factory
`create($input): self`

Returns the input instance if already a ListBucketsRequest, otherwise creates a new instance from the array.

### Getters
- `getBucketRegion(): ?string`
- `getContinuationToken(): ?string`
- `getMaxBuckets(): ?int`
- `getPrefix(): ?string`

### Setters (fluent, return $this)
- `setBucketRegion(?string $value): self`
- `setContinuationToken(?string $value): self`
- `setMaxBuckets(?int $value): self`
- `setPrefix(?string $value): self`

### Internal Request Method
`request(): Request` (marked @internal)

Builds the HTTP request (headers, query, URI, body). Throws `AsyncAws\Core\Exception\InvalidArgument` for missing required fields or invalid enum values.

### Inherited Region Methods
- `getRegion(): ?string`
- `setRegion(?string $region): void`

These are fed by the `'@region'` key and forwarded to the RequestContext by the client.
```

--------------------------------

### Set bucket lifecycle configuration with putBucketLifecycleConfiguration

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/ValueObject-bucket-configuration.md

Shows how to configure a bucket lifecycle rule using BucketLifecycleConfiguration and putBucketLifecycleConfiguration. The example sets an expiration rule for logs with a transition to STANDARD_IA storage class. Note that the Status field uses ExpirationStatus::ENABLED and the StorageClass uses TransitionStorageClass::STANDARD_IA.

```php
use AsyncAws\S3\ValueObject\BucketLifecycleConfiguration;

$s3->putBucketLifecycleConfiguration([
    'Bucket' => 'my-bucket',
    'LifecycleConfiguration' => [
        'Rules' => [[
            'ID' => 'expire-logs',
            'Status' => ExpirationStatus::ENABLED,
            'Filter' => ['Prefix' => 'logs/'],
            'Expiration' => ['Days' => 90],
            'Transitions' => [['Days' => 30, 'StorageClass' => TransitionStorageClass::STANDARD_IA]],
        ]],
    ],
])->resolve();
```

--------------------------------

### Create S3Client with NullProvider for anonymous access

Source: https://github.com/async-aws/s3/blob/master/_autodocs/endpoints.md

Use NullProvider to enable anonymous access to public buckets or emulators. The example sets an endpoint and pathStyleEndpoint to connect to a local emulator.

```php
use AsyncAws\Core\Credentials\NullProvider;

$s3 = new S3Client(['endpoint' => 'http://localhost:9000', 'pathStyleEndpoint' => true], new NullProvider());
```

--------------------------------

### Usage Example: Passing Enum Constants

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Enums.md

Demonstrates how to pass enum constants directly to S3 client methods that accept enum-typed inputs.

```APIDOC
## Usage Example: Passing Enum Constants

### Description
Pass the constant directly to any enum-typed input.

### Code Example
```php
use AsyncAws\S3\Enum\StorageClass;
use AsyncAws\S3\S3Client;

$s3->putObject([
    'Bucket' => 'my-bucket',
    'Key' => 'archive.zip',
    'Body' => $body,
    'StorageClass' => StorageClass::DEEP_ARCHIVE,
    'ServerSideEncryption' => ServerSideEncryption::AWS_KMS,
])->resolve();
```
```

--------------------------------

### Wait for bucket existence with bucketExists waiter

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-bucket-operations.md

Usage example for the bucketExists waiter. Creates a HeadBucketRequest for the bucket 'my-bucket', calls bucketExists, waits, and checks isSuccess() to determine if the bucket is usable. The waiter polls every 5 seconds up to 100 seconds.

```php
use AsyncAws\S3\Input\HeadBucketRequest;

$waiter = $s3->bucketExists(new HeadBucketRequest(['Bucket' => 'my-bucket']));
$created = $waiter->wait()->isSuccess();   // true once the bucket is usable
```

--------------------------------

### Declared constants in waiter classes (BucketExistsWaiter example)

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Waiters.md

Shows the class declaration and protected constants WAIT_TIMEOUT and WAIT_DELAY that are identical in all four waiter classes. The extractState() and refreshState() methods are described in comments, mapping HTTP statuses to waiter states and re-issuing the client request.

```php
class BucketExistsWaiter extends Waiter
{
    protected const WAIT_TIMEOUT = 100.0;   // seconds before giving up
    protected const WAIT_DELAY = 5.0;       // seconds between polls

    protected function extractState(Response $response, ?HttpException $exception): string
    // maps HTTP status to a waiter state constant
    // 200/301/403 → self::STATE_SUCCESS; 404 → self::STATE_PENDING (BucketExistsWaiter)
    // 200 → STATE_SUCCESS; 404 → STATE_PENDING (ObjectExistsWaiter)
    // 404 → STATE_SUCCESS; any exception → STATE_FAILURE; otherwise STATE_PENDING
    
    protected function refreshState(): Waiter
    // re-issues $this->awsClient->bucketExists($this->input) (or the matching method)
    // throws AsyncAws\Core\Exception\InvalidArgument when the client or input is missing:
    //   'missing client injected in waiter result' / 'missing last request injected in waiter result'
}
```

--------------------------------

### deleteObjects usage example

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-multipart-operations.md

Example of calling deleteObjects with an array input and iterating over the returned errors. Per-object errors do not throw; they are returned in the output.

```php
$out = $s3->deleteObjects([
    'Bucket' => 'my-bucket',
    'Delete' => ['Objects' => [['Key' => 'a.txt'], ['Key' => 'b.txt', 'VersionId' => 'v1']]],
]);
foreach ($out->getErrors() as $error) {
    printf("failed %s: %s (%s)\n", $error->getKey(), $error->getMessage(), $error->getCode());
}
```

--------------------------------

### Create PutObjectRequest input

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Input-request-classes.md

Shows how to create an input object using the static create() helper, which passes through an existing instance or creates a new one from an array.

```php
$input = PutObjectRequest::create($input); // passthrough if already a PutObjectRequest
```

--------------------------------

### Instantiate S3Client with custom endpoint and NullProvider

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client.md

Shows the canonical way to instantiate S3Client using the inherited constructor, as used in the test suite. It sets a custom S3-compatible endpoint, forces path-style URLs, and uses a NullProvider for credentials.

```php
$s3 = new S3Client([
    'endpoint'          => 'http://localhost:4569', // custom S3-compatible endpoint
    'pathStyleEndpoint' => true,                     // force path-style URLs
    // 'sendChunkedBody' => false,                   // read by getSignerFactories()
], new NullProvider());                              // AsyncAws\Core credential provider
```

--------------------------------

### Blocking wait with bucketExists

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Waiters.md

Shows how to create an S3Client, create a bucket, and use the bucketExists waiter with the blocking wait() method. The waiter polls every 5 seconds up to 100 seconds, and isSuccess() indicates whether the bucket is usable.

```php
use AsyncAws\S3\S3Client;

$s3 = new S3Client(['region' => 'us-east-1']);

// Blocking wait
$s3->createBucket(['Bucket' => 'my-bucket'])->resolve();
$waiter = $s3->bucketExists(['Bucket' => 'my-bucket']);
$waiter->wait();
if ($waiter->isSuccess()) {
    // bucket is usable
}
```

--------------------------------

### GET /{Bucket}?cors

Source: https://github.com/async-aws/s3/blob/master/_autodocs/endpoints.md

Retrieves the CORS configuration of a bucket.

```APIDOC
## GET /{Bucket}?cors

### Description
Retrieves the CORS configuration of a bucket.

### Method
GET

### Endpoint
/{Bucket}?cors

### Parameters
#### Path Parameters
- **Bucket** (string) - Required - Name of the bucket.

### Response
#### Success Response (200)
- **CORSRule** (array) - List of CORS rules.

#### Response Example
{
  "CORSRule": [
    {
      "AllowedMethod": ["GET"],
      "AllowedOrigin": ["https://example.com"]
    }
  ]
}
```

--------------------------------

### Using objectExists waiter

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-object-operations.md

Creates an ObjectExistsWaiter for a given bucket and key, then waits up to 100 seconds polling every 5 seconds. isSuccess() returns true once HEAD returns 200.

```php
$waiter = $s3->objectExists(['Bucket' => 'my-bucket', 'Key' => 'photos/sunset.jpg']);
$waiter->wait();                  // blocks up to 100s, polling every 5s
$ok = $waiter->isSuccess();       // true once HEAD returns 200
```

--------------------------------

### Waiter method signatures for bucketExists and bucketNotExists

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-bucket-operations.md

Method signatures for the two waiter entry points. Both accept a HeadBucketRequest input. bucketExists returns a BucketExistsWaiter that succeeds on HTTP status 200, 301, or 403 and stays pending on 404. bucketNotExists returns a BucketNotExistsWaiter that succeeds on 404. Both poll every 5.0 seconds up to 100.0 seconds and re-issue the corresponding operation for state refresh.

```php
public function bucketExists($input): BucketExistsWaiter      // HeadBucketRequest $input
public function bucketNotExists($input): BucketNotExistsWaiter
```

--------------------------------

### Create bucket with region

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-bucket-operations.md

Creates a bucket in the EU West 2 region. The resolve() call waits for the operation to complete.

```php
$result = $s3->createBucket([
    'Bucket' => 'my-bucket',
    'CreateBucketConfiguration' => ['LocationConstraint' => BucketLocationConstraint::EU_WEST_2],
])->resolve();

```

--------------------------------

### Constructor

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/SignerV4ForS3.md

Creates a new SignerV4ForS3 instance with the given scope name, region, and optional signer options.

```APIDOC
## Constructor

### Description
Creates a new SignerV4ForS3 instance.

### Method
__construct

### Signature
```php
public function __construct(string $scopeName, string $region, array $s3SignerOptions = [])
```

### Parameters
- **$scopeName** (string) - Required - Credential scope service name (`'s3'` when used by the client)
- **$region** (string) - Required - AWS region used in credential scope
- **$s3SignerOptions** (array{ sendChunkedBody?: bool }) - Optional - Signer options; `sendChunkedBody` defaults to `false`

### Errors
Any key other than `sendChunkedBody` causes an immediate `AsyncAws\Core\Exception\InvalidArgument`:

```php
throw new InvalidArgument(\sprintf('Invalid option(s) "%s" passed to "%s::%s". ', implode('", "', array_keys($s3SignerOptions)), __CLASS__, __METHOD__));
```
```

--------------------------------

### InvalidArgument for missing required field

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Input-request-classes.md

Shows the exception thrown by request() when a required field is missing, using 'Bucket' as an example.

```php
throw new InvalidArgument(\sprintf('Missing parameter "Bucket" for "%s". The value cannot be null.', __CLASS__));
```

--------------------------------

### createBucket($input): CreateBucketOutput

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-bucket-operations.md

Creates a new S3 bucket. Accepts an array or CreateBucketRequest object with bucket configuration options, returns a CreateBucketOutput, and throws exceptions if the bucket already exists or is owned by you.

```APIDOC
## createBucket($input): CreateBucketOutput

### Description
Creates a new S3 bucket. Accepts an array or CreateBucketRequest object with bucket configuration options, returns a CreateBucketOutput, and throws exceptions if the bucket already exists or is owned by you.

### Method
createBucket

### Endpoint
N/A (SDK method)

### Parameters
#### Input Parameters
- **Bucket** (string) - Required - Bucket name
- **ACL** (BucketCannedACL::*|null) - Optional - `private`(default at AWS), `public-read`, `public-read-write`, `authenticated-read`
- **CreateBucketConfiguration** (CreateBucketConfiguration|array|null) - Optional - Region (`LocationConstraint`), `LocationInfo`, `BucketInfo`, `Tags` (see [ValueObject-bucket-configuration.md](ValueObject-bucket-configuration.md))
- **GrantFullControl**…**GrantWriteACP** (5 keys) (string|null) - Optional - `x-amz-grant-*` headers
- **ObjectLockEnabledForBucket** (bool|null) - Optional - Enables Object Lock on creation
- **ObjectOwnership** (ObjectOwnership::*|null) - Optional - `BucketOwnerEnforced`, `BucketOwnerPreferred`, `ObjectWriter`
- **BucketNamespace** (BucketNamespace::*|null) - Optional - `global` (default) or `account-regional`

### Request Example
```php
$result = $s3->createBucket([
    'Bucket' => 'my-bucket',
    'CreateBucketConfiguration' => ['LocationConstraint' => BucketLocationConstraint::EU_WEST_2],
])->resolve();
```

### Response
#### Success Response
Returns `CreateBucketOutput` — `getLocation(): ?string`.

#### Error Handling
```php
use AsyncAws\S3\Exception\BucketAlreadyOwnedByYouException;

try {
    $s3->createBucket(['Bucket' => 'my-bucket'])->resolve();
} catch (BucketAlreadyOwnedByYouException $e) {
    // bucket exists and belongs to you — treat as OK, or delete and retry
}
```

### Throws
- `BucketAlreadyExistsException`
- `BucketAlreadyOwnedByYouException`
```

--------------------------------

### Directly sign a request with SignerV4ForS3

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/SignerV4ForS3.md

Constructs a SignerV4ForS3 instance, a Request, and a RequestContext, then calls sign() to add Authorization, x-amz-date, and x-amz-content-sha256 headers. Useful for testing the signer directly.

```php
use AsyncAws\Core\Credentials\Credentials;
use AsyncAws\Core\Request;
use AsyncAws\Core\RequestContext;
use AsyncAws\S3\Signer\SignerV4ForS3;

$signer = new SignerV4ForS3('s3', 'us-east-1', ['sendChunkedBody' => true]);
$request = new Request('PUT', '/my-bucket/key', [], ['content-type' => 'text/plain'], $bodyStream);
$signer->sign($request, new Credentials('AKID', 'secret'), new RequestContext(['operation' => 'PutObject']));
// $request now carries Authorization, x-amz-date, x-amz-content-sha256 headers
```

--------------------------------

### GET /{Bucket}?list-type=2

Source: https://github.com/async-aws/s3/blob/master/_autodocs/endpoints.md

Lists objects in a bucket using the S3 ListObjectsV2 API. Supports pagination via continuation-token.

```APIDOC
## GET /{Bucket}?list-type=2

### Description
Lists objects in a bucket using the S3 ListObjectsV2 API.

### Method
GET

### Endpoint
/{Bucket}?list-type=2

### Parameters
#### Path Parameters
- **Bucket** (string) - Required - Name of the bucket.

#### Query Parameters
- **delimiter** (string) - Optional - A delimiter to group keys.
- **encoding-type** (string) - Optional - Encoding type for keys.
- **max-keys** (string) - Optional - Maximum number of keys to return.
- **prefix** (string) - Optional - Limits response to keys with the specified prefix.
- **continuation-token** (string) - Optional - Token to continue a previous list request.
- **fetch-owner** (string) - Optional - Indicates whether to fetch the owner.
- **start-after** (string) - Optional - Key to start listing after.

### Response
#### Success Response (200)
- **Contents** (array) - List of objects.
- **NextContinuationToken** (string) - Token for next page.

#### Response Example
{
  "Contents": [
    {
      "Key": "file.txt",
      "Size": 123
    }
  ],
  "NextContinuationToken": "token"
}
```

--------------------------------

### Validation Example: Invalid Enum Value

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Enums.md

Shows how an invalid enum value causes a synchronous exception when calling the request() method.

```APIDOC
## Validation Example: Invalid Enum Value

### Description
An enum value that fails `exists()` makes the input `request()` throw synchronously.

### Code Example
```php
use AsyncAws\Core\Exception\InvalidArgument;

try {
    $s3->putObject(['Bucket' => 'b', 'Key' => 'k', 'Body' => 'x', 'StorageClass' => 'CUSTOM'])->getEtag();
} catch (InvalidArgument $e) {
    // Invalid parameter "StorageClass" for "AsyncAws\S3\Input\PutObjectRequest"...
}
```
```

--------------------------------

### GET /{Bucket}/{Key}?uploadId

Source: https://github.com/async-aws/s3/blob/master/_autodocs/endpoints.md

Lists the parts that have been uploaded for a specific multipart upload. Supports pagination via max-parts and part-number-marker.

```APIDOC
## GET /{Bucket}/{Key}?uploadId

### Description
Lists the parts that have been uploaded for a specific multipart upload. Supports pagination via max-parts and part-number-marker.

### Method
GET

### Endpoint
`/{Bucket}/{Key}?uploadId`

### Parameters
#### Path Parameters
- **Bucket** (string) - Required - The bucket name.
- **Key** (string) - Required - The object key.

#### Query Parameters
- **uploadId** (string) - Required - The upload ID to list parts for.
- **max-parts** (integer) - Optional - Maximum number of parts to return.
- **part-number-marker** (integer) - Optional - The part number to start listing from.

### Request Example
No request body is required.

### Response
#### Success Response (200)
- **Parts** (array) - List of parts.
  - **PartNumber** (integer) - The part number.
  - **ETag** (string) - The ETag of the part.
  - **Size** (integer) - The size of the part.

#### Response Example
{
  "Parts": [
    {
      "PartNumber": 1,
      "ETag": "\"example-etag\"",
      "Size": 5242880
    }
  ]
}
```

--------------------------------

### PutBucketLifecycleConfigurationOutput

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Result-output-classes.md

Output class for the PutBucketLifecycleConfiguration operation, providing the transition default minimum object size.

```APIDOC
## PutBucketLifecycleConfigurationOutput

### Description
Represents the result of a PutBucketLifecycleConfiguration operation. Provides the default minimum object size for transitions.

### Getters
- **getTransitionDefaultMinimumObjectSize(): ?string** - The default minimum object size for transitions.
```

--------------------------------

### InvalidArgument for invalid enum value

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Input-request-classes.md

Shows the exception thrown by request() when an enum field fails the Enum::exists() check, using 'ACL' and 'ObjectCannedACL' as examples.

```php
throw new InvalidArgument(\sprintf('Invalid parameter "ACL" for "%s". The value "%s" is not a valid "ObjectCannedACL".', __CLASS__, $this->acl));
```

--------------------------------

### putBucketVersioning($input): Result

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-bucket-operations.md

Sets the versioning state for a bucket. Accepts an input array with the bucket name and versioning configuration, and returns a Result object.

```APIDOC
## putBucketVersioning($input): Result

### Description
Sets the versioning state for a bucket.

### Method
SDK method

### Parameters
#### Input
- **Bucket** (string) - Required - The name of the bucket.
- **ContentMD5** (string|null) - Optional - The base64-encoded 128-bit MD5 digest of the message.
- **ChecksumAlgorithm** (ChecksumAlgorithm::*|null) - Optional - The algorithm used to create the checksum.
- **MFA** (string|null) - Optional - The concatenation of the authentication device's serial number, a space, and the value displayed on the authentication device.
- **VersioningConfiguration** (VersioningConfiguration|array) - Required - The versioning configuration. Must include 'Status' (BucketVersioningStatus::ENABLED|SUSPENDED) and optionally 'MFADelete' (MFADelete::*).
- **ExpectedBucketOwner** (string|null) - Optional - The expected account ID of the bucket owner.
- **'@region'** (string|null) - Optional - The AWS region for the request.

### Request Example
```php
$s3->putBucketVersioning([
    'Bucket' => 'my-bucket',
    'VersioningConfiguration' => ['Status' => BucketVersioningStatus::ENABLED],
])->resolve();
```

### Returns
- **Result** - The result of the operation.
```

--------------------------------

### putObject error handling with InvalidRequestException

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-object-operations.md

Shows how to catch an InvalidRequestException when calling putObject. The example calls resolve() to trigger the request and then inspects the AWS error message.

```php
use AsyncAws\S3\Exception\InvalidRequestException;

try {
    $s3->putObject(['Bucket' => 'my-bucket', 'Key' => 'k', 'Body' => 'v'])->resolve();
} catch (InvalidRequestException $e) {
    // AWS reported an invalid parameter/header — inspect $e->getAwsMessage()
}
```

--------------------------------

### GET /{Bucket}/{Key} - getObject

Source: https://github.com/async-aws/s3/blob/master/_autodocs/endpoints.md

Retrieves an object from the bucket. Supports query parameters for response overrides and versioning, and headers for conditional requests, range, encryption, and request payer.

```APIDOC
## GET /{Bucket}/{Key}

### Description
Retrieves an object from the bucket. Supports query parameters for response overrides and versioning, and headers for conditional requests, range, encryption, and request payer.

### Method
GET

### Endpoint
`/{Bucket}/{Key}`

### Parameters
#### Path Parameters
- **Bucket** (string) - Required - The name of the bucket.
- **Key** (string) - Required - The object key.

#### Query Parameters
- **response-cache-control** (string) - Optional - Sets the Cache-Control header in the response.
- **response-content-disposition** (string) - Optional - Sets the Content-Disposition header in the response.
- **response-content-encoding** (string) - Optional - Sets the Content-Encoding header in the response.
- **response-content-language** (string) - Optional - Sets the Content-Language header in the response.
- **response-content-type** (string) - Optional - Sets the Content-Type header in the response.
- **response-expires** (string) - Optional - Sets the Expires header in the response.
- **versionId** (string) - Optional - Version of the object to retrieve.
- **partNumber** (integer) - Optional - Part number of a multipart upload to retrieve.

#### Headers
- **if-*** (string) - Optional - Conditional headers such as If-Match, If-None-Match, etc.
- **range** (string) - Optional - Byte range to retrieve.
- **x-amz-server-side-encryption-customer-*** (string) - Optional - Customer-provided encryption keys.
- **x-amz-request-payer** (string) - Optional - Confirms that the requester knows they will be charged.
- **x-amz-expected-bucket-owner** (string) - Optional - The expected owner of the bucket.
- **x-amz-checksum-mode** (string) - Optional - When set to ENABLED, returns the checksum of the object.

### Request Example
```
GET /my-bucket/my-object?versionId=abc123 HTTP/1.1
Host: s3.amazonaws.com
Range: bytes=0-1023
```

### Response
#### Success Response (200)
The response body contains the object content.

#### Response Example
```
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 1024

[object content]
```
```

--------------------------------

### Catch local validation error InvalidArgument

Source: https://github.com/async-aws/s3/blob/master/_autodocs/errors.md

Catches local validation errors before the request is sent. The example passes a null UploadId to uploadPart, which triggers InvalidArgument with a message about the missing parameter.

```php
use AsyncAws\Core\Exception\InvalidArgument;

try {
    $s3->uploadPart(['Bucket' => 'b', 'Key' => 'k', 'UploadId' => null, 'PartNumber' => 1]);
} catch (InvalidArgument $e) {
    // Missing parameter "UploadId" ...
}
```

--------------------------------

### Catch typed service error NoSuchKeyException

Source: https://github.com/async-aws/s3/blob/master/_autodocs/errors.md

Catches a known service error code. The example retrieves an object and reads its body, catching NoSuchKeyException to print the AWS message, code, and status.

```php
use AsyncAws\S3\Exception\NoSuchKeyException;

try {
    $s3->getObject(['Bucket' => 'my-bucket', 'Key' => 'missing.txt'])->getBody();
} catch (NoSuchKeyException $e) {
    fprintf(STDERR, "missing: %s (code=%s status=%d)\n", $e->getAwsMessage(), $e->getAwsCode(), $e->getStatusCode());
}
```

--------------------------------

### CreateBucketRequest

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/Input-request-classes.md

Creates a new bucket. Requires the bucket name.

```APIDOC
## PUT /{Bucket}

### Description
Creates a new bucket. Requires the bucket name.

### Method
PUT

### Endpoint
/{Bucket}

### Parameters
#### Path Parameters
- **Bucket** (string) - Required - The bucket name.

### Request Example
```
PUT /my-bucket
```

### Response
#### Success Response (200)
- **Location** (string) - The location of the created bucket.

#### Response Example
```
HTTP/1.1 200 OK
Location: /my-bucket
```
```

--------------------------------

### Iterate buckets with auto-pagination and current page

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-bucket-operations.md

Iterates over buckets. The first loop auto-paginates through all buckets; the second uses MaxBuckets and getBuckets(true) to fetch only the current page.

```php
foreach ($s3->listBuckets() as $bucket) {          // iterates ALL buckets (auto-pagination)
    echo $bucket->getName() . "\n";
}
foreach ($s3->listBuckets(['MaxBuckets' => 10])->getBuckets(true) as $bucket) {
    echo $bucket->getName() . "\n";                // current page only
}
```

--------------------------------

### createBucket method signature

Source: https://github.com/async-aws/s3/blob/master/_autodocs/api-reference/S3Client-bucket-operations.md

Method signature for creating an S3 bucket. Throws BucketAlreadyExistsException and BucketAlreadyOwnedByYouException.

```php
public function createBucket($input): CreateBucketOutput

```
Tokens:
Raw