SDK for PHP 3.x

S3ClientInterface extends AwsClientInterface
in

Represents an AWS client.

Table of Contents

Methods

__call()  : ResultInterface
Creates and executes a command for an operation by name.
copy()  : ResultInterface
Copy an object of any size to a different location.
copyAsync()  : PromiseInterface
Copy an object of any size to a different location asynchronously.
createPresignedRequest()  : RequestInterface
Create a pre-signed URL for the given S3 command object.
deleteMatchingObjects()  : mixed
Deletes objects from Amazon S3 that match the result of a ListObjects operation. For example, this allows you to do things like delete all objects that match a specific key prefix.
deleteMatchingObjectsAsync()  : PromiseInterface
Deletes objects from Amazon S3 that match the result of a ListObjects operation. For example, this allows you to do things like delete all objects that match a specific key prefix.
determineBucketRegion()  : string
Returns the region in which a given bucket is located.
determineBucketRegionAsync()  : PromiseInterface
Returns a promise fulfilled with the region in which a given bucket is located.
doesBucketExist()  : bool
doesBucketExistV2()  : bool
Determines whether or not a bucket exists by name. This method uses S3's HeadBucket operation and requires the relevant bucket permissions in the default case to prevent errors.
doesObjectExist()  : bool
doesObjectExistV2()  : bool
Determines whether or not an object exists by name. This method uses S3's HeadObject operation and requires the relevant bucket and object permissions to prevent errors.
downloadBucket()  : mixed
Downloads a bucket to the local filesystem
downloadBucketAsync()  : PromiseInterface
Downloads a bucket to the local filesystem
execute()  : ResultInterface
Execute a single command.
executeAsync()  : PromiseInterface
Execute a command asynchronously.
getApi()  : Service
Get the service description associated with the client.
getCommand()  : CommandInterface
Create a command for an operation name.
getConfig()  : mixed|null
Get a client configuration value.
getCredentials()  : PromiseInterface
Returns a promise that is fulfilled with an {@see \Aws\Credentials\CredentialsInterface} object.
getEndpoint()  : UriInterface
Gets the default endpoint, or base URL, used by the client.
getHandlerList()  : HandlerList
Get the handler list used to transfer commands.
getIterator()  : Iterator
Get a resource iterator for the specified operation.
getObjectUrl()  : string
Returns the URL to an object identified by its bucket and key.
getPaginator()  : ResultPaginator
Get a result paginator for the specified operation.
getRegion()  : string
Get the region to which the client is configured to send requests.
getWaiter()  : Waiter
Get a waiter that waits until a resource is in a particular state.
registerStreamWrapper()  : mixed
Register the Amazon S3 stream wrapper with this client instance.
registerStreamWrapperV2()  : mixed
Registers the Amazon S3 stream wrapper with this client instance.
upload()  : ResultInterface
Upload a file, stream, or string to a bucket.
uploadAsync()  : PromiseInterface
Upload a file, stream, or string to a bucket asynchronously.
uploadDirectory()  : mixed
Recursively uploads all files in a given directory to a given bucket.
uploadDirectoryAsync()  : PromiseInterface
Recursively uploads all files in a given directory to a given bucket.
waitUntil()  : void
Wait until a resource is in a particular state.

Methods

__call()

Creates and executes a command for an operation by name.

public __call(string $name, array<string|int, mixed> $arguments) : ResultInterface

Suffixing an operation name with "Async" will return a promise that can be used to execute commands asynchronously.

Parameters
$name : string

Name of the command to execute.

$arguments : array<string|int, mixed>

Arguments to pass to the getCommand method.

Tags
throws
Exception
Return values
ResultInterface

copy()

Copy an object of any size to a different location.

public copy(string $fromBucket, string $fromKey, string $destBucket, string $destKey[, string $acl = 'private' ][, array<string|int, mixed> $options = [] ]) : ResultInterface

If the upload size exceeds the maximum allowable size for direct S3 copying, a multipart copy will be used.

The options array accepts the following options:

  • before_upload: (callable) Callback to invoke before any upload operations during the upload process. The callback should have a function signature like function (Aws\Command $command) {...}.
  • concurrency: (int, default=int(5)) Maximum number of concurrent UploadPart operations allowed during a multipart upload.
  • params: (array, default=array([])) Custom parameters to use with the upload. For single uploads, they must correspond to those used for the CopyObject operation. For multipart uploads, they correspond to the parameters of the CreateMultipartUpload operation.
  • part_size: (int) Part size to use when doing a multipart upload.
Parameters
$fromBucket : string

Bucket where the copy source resides.

$fromKey : string

Key of the copy source.

$destBucket : string

Bucket to which to copy the object.

$destKey : string

Key to which to copy the object.

$acl : string = 'private'

ACL to apply to the copy (default: private).

$options : array<string|int, mixed> = []

Options used to configure the upload process.

Tags
see
MultipartCopy

for more info about multipart uploads.

Return values
ResultInterface —

Returns the result of the copy.

copyAsync()

Copy an object of any size to a different location asynchronously.

public copyAsync(string $fromBucket, string $fromKey, string $destBucket, string $destKey[, string $acl = 'private' ][, array<string|int, mixed> $options = [] ]) : PromiseInterface
Parameters
$fromBucket : string

Bucket where the copy source resides.

$fromKey : string

Key of the copy source.

$destBucket : string

Bucket to which to copy the object.

$destKey : string

Key to which to copy the object.

$acl : string = 'private'

ACL to apply to the copy (default: private).

$options : array<string|int, mixed> = []

Options used to configure the upload process.

Tags
see
self::copy

for more info about the parameters above.

Return values
PromiseInterface —

Returns a promise that will be fulfilled with the result of the copy.

createPresignedRequest()

Create a pre-signed URL for the given S3 command object.

public createPresignedRequest(CommandInterface $command, int|string|DateTimeInterface $expires[, array<string|int, mixed> $options = [] ]) : RequestInterface
Parameters
$command : CommandInterface

Command to create a pre-signed URL for.

$expires : int|string|DateTimeInterface

The time at which the URL should expire. This can be a Unix timestamp, a PHP DateTime object, or a string that can be evaluated by strtotime().

$options : array<string|int, mixed> = []
Return values
RequestInterface

deleteMatchingObjects()

Deletes objects from Amazon S3 that match the result of a ListObjects operation. For example, this allows you to do things like delete all objects that match a specific key prefix.

public deleteMatchingObjects(string $bucket[, string $prefix = '' ][, string $regex = '' ][, array<string|int, mixed> $options = [] ]) : mixed
Parameters
$bucket : string

Bucket that contains the object keys

$prefix : string = ''

Optionally delete only objects under this key prefix

$regex : string = ''

Delete only objects that match this regex

$options : array<string|int, mixed> = []

Aws\S3\BatchDelete options array.

Tags
see
S3Client::listObjects
throws
RuntimeException

if no prefix and no regex is given

deleteMatchingObjectsAsync()

Deletes objects from Amazon S3 that match the result of a ListObjects operation. For example, this allows you to do things like delete all objects that match a specific key prefix.

public deleteMatchingObjectsAsync(string $bucket[, string $prefix = '' ][, string $regex = '' ][, array<string|int, mixed> $options = [] ]) : PromiseInterface
Parameters
$bucket : string

Bucket that contains the object keys

$prefix : string = ''

Optionally delete only objects under this key prefix

$regex : string = ''

Delete only objects that match this regex

$options : array<string|int, mixed> = []

Aws\S3\BatchDelete options array.

Tags
see
S3Client::listObjects
Return values
PromiseInterface —

A promise that is settled when matching objects are deleted.

determineBucketRegion()

Returns the region in which a given bucket is located.

public determineBucketRegion(string $bucketName) : string
Parameters
$bucketName : string
Return values
string

determineBucketRegionAsync()

Returns a promise fulfilled with the region in which a given bucket is located.

public determineBucketRegionAsync(string $bucketName) : PromiseInterface
Parameters
$bucketName : string
Return values
PromiseInterface

doesBucketExist()

public doesBucketExist(string $bucket) : bool
Parameters
$bucket : string

The name of the bucket

Tags
deprecated

Use doesBucketExistV2() instead

Determines whether or not a bucket exists by name.

Return values
bool

doesBucketExistV2()

Determines whether or not a bucket exists by name. This method uses S3's HeadBucket operation and requires the relevant bucket permissions in the default case to prevent errors.

public doesBucketExistV2(string $bucket, bool $accept403) : bool
Parameters
$bucket : string

The name of the bucket

$accept403 : bool

Set to true for this method to return true in the case of invalid bucket-level permissions. Credentials MUST be valid to avoid inaccuracies. Using the default value of false will cause an exception to be thrown instead.

Tags
throws
S3Exception|Exception

if there is an unhandled exception

Return values
bool

doesObjectExist()

public doesObjectExist(string $bucket, string $key[, array<string|int, mixed> $options = [] ]) : bool
Parameters
$bucket : string

The name of the bucket

$key : string

The key of the object

$options : array<string|int, mixed> = []

Additional options available in the HeadObject operation (e.g., VersionId).

Tags
deprecated

Use doesObjectExistV2() instead

Determines whether or not an object exists by name.

Return values
bool

doesObjectExistV2()

Determines whether or not an object exists by name. This method uses S3's HeadObject operation and requires the relevant bucket and object permissions to prevent errors.

public doesObjectExistV2(string $bucket, string $key[, bool $includeDeleteMarkers = false ][, array<string|int, mixed> $options = [] ]) : bool
Parameters
$bucket : string

The name of the bucket

$key : string

The key of the object

$includeDeleteMarkers : bool = false

Set to true to consider delete markers existing objects. Using the default value of false will ignore delete markers and return false.

$options : array<string|int, mixed> = []

Additional options available in the HeadObject operation (e.g., VersionId).

Tags
throws
S3Exception|Exception

if there is an unhandled exception

Return values
bool

downloadBucket()

Downloads a bucket to the local filesystem

public downloadBucket(string $directory, string $bucket[, string $keyPrefix = '' ][, array<string|int, mixed> $options = [] ]) : mixed
Parameters
$directory : string

Directory to download to

$bucket : string

Bucket to download from

$keyPrefix : string = ''

Only download objects that use this key prefix

$options : array<string|int, mixed> = []

Options available in Aws\S3\Transfer::__construct

downloadBucketAsync()

Downloads a bucket to the local filesystem

public downloadBucketAsync(string $directory, string $bucket[, string $keyPrefix = '' ][, array<string|int, mixed> $options = [] ]) : PromiseInterface
Parameters
$directory : string

Directory to download to

$bucket : string

Bucket to download from

$keyPrefix : string = ''

Only download objects that use this key prefix

$options : array<string|int, mixed> = []

Options available in Aws\S3\Transfer::__construct

Return values
PromiseInterface —

A promise that is settled when the download is complete.

getApi()

Get the service description associated with the client.

public getApi() : Service
Return values
Service

getCommand()

Create a command for an operation name.

public getCommand(string $name[, array<string|int, mixed> $args = [] ]) : CommandInterface

Special keys may be set on the command to control how it behaves, including:

  • @http: Associative array of transfer specific options to apply to the request that is serialized for this command. Available keys include "proxy", "verify", "timeout", "connect_timeout", "debug", "delay", and "headers".
Parameters
$name : string

Name of the operation to use in the command

$args : array<string|int, mixed> = []

Arguments to pass to the command

Tags
throws
InvalidArgumentException

if no command can be found by name

Return values
CommandInterface

getConfig()

Get a client configuration value.

public getConfig([string|null $option = null ]) : mixed|null
Parameters
$option : string|null = null

The option to retrieve. Pass null to retrieve all options.

Return values
mixed|null

getCredentials()

Returns a promise that is fulfilled with an {@see \Aws\Credentials\CredentialsInterface} object.

public getCredentials() : PromiseInterface

If you need the credentials synchronously, then call the wait() method on the returned promise.

Return values
PromiseInterface

getEndpoint()

Gets the default endpoint, or base URL, used by the client.

public getEndpoint() : UriInterface
Return values
UriInterface

getHandlerList()

Get the handler list used to transfer commands.

public getHandlerList() : HandlerList

This list can be modified to add middleware or to change the underlying handler used to send HTTP requests.

Return values
HandlerList

getIterator()

Get a resource iterator for the specified operation.

public getIterator(string $name[, array<string|int, mixed> $args = [] ]) : Iterator
Parameters
$name : string

Name of the iterator to retrieve.

$args : array<string|int, mixed> = []

Command arguments to use with each command.

Tags
throws
UnexpectedValueException

if the iterator config is invalid.

Return values
Iterator

getObjectUrl()

Returns the URL to an object identified by its bucket and key.

public getObjectUrl(string $bucket, string $key) : string

The URL returned by this method is not signed nor does it ensure that the bucket and key given to the method exist. If you need a signed URL, then use the S3Client::createPresignedRequest method and get the URI of the signed request.

Parameters
$bucket : string

The name of the bucket where the object is located

$key : string

The key of the object

Return values
string —

The URL to the object

getPaginator()

Get a result paginator for the specified operation.

public getPaginator(string $name[, array<string|int, mixed> $args = [] ]) : ResultPaginator
Parameters
$name : string

Name of the operation used for iterator

$args : array<string|int, mixed> = []

Command args to be used with each command

Tags
throws
UnexpectedValueException

if the iterator config is invalid.

Return values
ResultPaginator

getRegion()

Get the region to which the client is configured to send requests.

public getRegion() : string
Return values
string

getWaiter()

Get a waiter that waits until a resource is in a particular state.

public getWaiter(string|callable $name[, array<string|int, mixed> $args = [] ]) : Waiter

Retrieving a waiter can be useful when you wish to wait asynchronously:

$waiter = $client->getWaiter('foo', ['bar' => 'baz']); $waiter->promise()->then(function () { echo 'Done!'; });

Parameters
$name : string|callable

Name of the waiter that defines the wait configuration and conditions.

$args : array<string|int, mixed> = []

Args to be used with each command executed by the waiter. Waiter configuration options can be provided in an associative array in the @waiter key.

Tags
throws
UnexpectedValueException

if the waiter is invalid.

Return values
Waiter

registerStreamWrapper()

Register the Amazon S3 stream wrapper with this client instance.

public registerStreamWrapper() : mixed

registerStreamWrapperV2()

Registers the Amazon S3 stream wrapper with this client instance.

public registerStreamWrapperV2() : mixed

This version uses doesObjectExistV2 and doesBucketExistV2 to check resource existence.

upload()

Upload a file, stream, or string to a bucket.

public upload(string $bucket, string $key, mixed $body[, string $acl = 'private' ][, array<string|int, mixed> $options = [] ]) : ResultInterface

If the upload size exceeds the specified threshold, the upload will be performed using concurrent multipart uploads.

The options array accepts the following options:

  • before_upload: (callable) Callback to invoke before any upload operations during the upload process. The callback should have a function signature like function (Aws\Command $command) {...}.
  • concurrency: (int, default=int(3)) Maximum number of concurrent UploadPart operations allowed during a multipart upload.
  • mup_threshold: (int, default=int(16777216)) The size, in bytes, allowed before the upload must be sent via a multipart upload. Default: 16 MB.
  • params: (array, default=array([])) Custom parameters to use with the upload. For single uploads, they must correspond to those used for the PutObject operation. For multipart uploads, they correspond to the parameters of the CreateMultipartUpload operation.
  • part_size: (int) Part size to use when doing a multipart upload.
Parameters
$bucket : string

Bucket to upload the object.

$key : string

Key of the object.

$body : mixed

Object data to upload. Can be a StreamInterface, PHP stream resource, or a string of data to upload.

$acl : string = 'private'

ACL to apply to the object (default: private).

$options : array<string|int, mixed> = []

Options used to configure the upload process.

Tags
see
MultipartUploader

for more info about multipart uploads.

Return values
ResultInterface —

Returns the result of the upload.

uploadAsync()

Upload a file, stream, or string to a bucket asynchronously.

public uploadAsync(string $bucket, string $key, mixed $body[, string $acl = 'private' ][, array<string|int, mixed> $options = [] ]) : PromiseInterface
Parameters
$bucket : string

Bucket to upload the object.

$key : string

Key of the object.

$body : mixed

Object data to upload. Can be a StreamInterface, PHP stream resource, or a string of data to upload.

$acl : string = 'private'

ACL to apply to the object (default: private).

$options : array<string|int, mixed> = []

Options used to configure the upload process.

Tags
see
self::upload
Return values
PromiseInterface —

Returns a promise that will be fulfilled with the result of the upload.

uploadDirectory()

Recursively uploads all files in a given directory to a given bucket.

public uploadDirectory(string $directory, string $bucket[, string $keyPrefix = null ][, array<string|int, mixed> $options = [] ]) : mixed
Parameters
$directory : string

Full path to a directory to upload

$bucket : string

Name of the bucket

$keyPrefix : string = null

Virtual directory key prefix to add to each upload

$options : array<string|int, mixed> = []

Options available in Aws\S3\Transfer::__construct

Tags
see
Transfer

for more options and customization

uploadDirectoryAsync()

Recursively uploads all files in a given directory to a given bucket.

public uploadDirectoryAsync(string $directory, string $bucket[, string $keyPrefix = null ][, array<string|int, mixed> $options = [] ]) : PromiseInterface
Parameters
$directory : string

Full path to a directory to upload

$bucket : string

Name of the bucket

$keyPrefix : string = null

Virtual directory key prefix to add to each upload

$options : array<string|int, mixed> = []

Options available in Aws\S3\Transfer::__construct

Tags
see
Transfer

for more options and customization

Return values
PromiseInterface —

A promise that is settled when the upload is complete.

waitUntil()

Wait until a resource is in a particular state.

public waitUntil(string|callable $name[, array<string|int, mixed> $args = [] ]) : void
Parameters
$name : string|callable

Name of the waiter that defines the wait configuration and conditions.

$args : array<string|int, mixed> = []

Args to be used with each command executed by the waiter. Waiter configuration options can be provided in an associative array in the @waiter key.

Tags
throws
UnexpectedValueException

if the waiter is invalid.

On this page