Menu
Amazon Simple Storage Service
Developer Guide (API Version 2006-03-01)

Using the AWS PHP SDK for Multipart Upload (High-Level API)

Amazon S3 allows you to upload large files in multiple parts. You must use a multipart upload for files larger than 5 GB. The AWS SDK for PHP exposes the high-level Aws\S3\Model\MultipartUpload\UploadBuilder class that simplifies multipart uploads.

The Aws\S3\Model\MultipartUpload\UploadBuilder class is best used for a simple multipart upload. If you need to pause and resume multipart uploads, vary part sizes during the upload, or do not know the size of the data in advance, you should use the low-level PHP API. For more information, see Using the AWS PHP SDK for Multipart Upload (Low-Level API).

For more information about multipart uploads, see Uploading Objects Using Multipart Upload API. For information on uploading files that are less than 5GB in size, see Upload an Object Using the AWS SDK for PHP.

Upload a File Using the High-Level Multipart Upload

This topic guides you through using the high-level Aws\S3\Model\MultipartUpload\UploadBuilder class from the AWS SDK for PHP for multipart file uploads.

Note

This topic assumes that you are already following the instructions for Using the AWS SDK for PHP and Running PHP Examples and have the AWS SDK for PHP properly installed.

High-Level Multipart File Upload Process

1

Create an instance of an Amazon S3 client by using the Aws\S3\S3Client class factory() method.

2

Create an instance of the UploadBuilder using the Amazon S3 Aws\S3\Model\MultipartUpload\UploadBuilder class newInstance() method, which is inherited from the Aws\Common\Model\MultipartUpload\AbstractUploadBuilder class. For the UploadBuilder object set the client, the bucket name, and the key name using the setClient(), setBucket(), and setKey() methods. Set the path and name of the file you want to upload with the setSource() method.

3

Execute the UploadBuilder object's build() method to build the appropriate uploader transfer object based on the builder options you set. (The transfer object is of a subclass of the Aws\S3\Model\MultipartUpload\AbstractTransfer class.)

4

Execute the upload() method of the built transfer object to perform the upload.

The following PHP code sample demonstrates how to upload a file using the high-level UploadBuilder object.

Copy
use Aws\Common\Exception\MultipartUploadException; use Aws\S3\Model\MultipartUpload\UploadBuilder; use Aws\S3\S3Client; $bucket = '*** Your Bucket Name ***'; $keyname = '*** Your Object Key ***'; // Instantiate the client. $s3 = S3Client::factory(); // Prepare the upload parameters. $uploader = UploadBuilder::newInstance() ->setClient($s3) ->setSource('/path/to/large/file.mov') ->setBucket($bucket) ->setKey($keyname) ->build(); // Perform the upload. Abort the upload if something goes wrong. try { $uploader->upload(); echo "Upload complete.\n"; } catch (MultipartUploadException $e) { $uploader->abort(); echo "Upload failed.\n"; echo $e->getMessage() . "\n"; }

Example of a Multipart Upload of a File to an Amazon S3 Bucket Using the High-level UploadBuilder

The following PHP example uploads a file to an Amazon S3 bucket. The example demonstrates how to set advanced options for the UploadBuilder object. For example, you can use the setMinPartSize() method to set the part size you want to use for the multipart upload and the setOption() method to set optional file metadata or an access control list (ACL).

The example also demonstrates how to upload file parts in parallel by setting the concurrency option using the setConcurrency() method for the UploadBuilder object. The example creates a transfer object that will attempt to upload three parts in parallel until the entire file has been uploaded. For information about running the PHP examples in this guide, go to Running PHP Examples.

Copy
<?php // Include the AWS SDK using the Composer autoloader. require 'vendor/autoload.php'; use Aws\Common\Exception\MultipartUploadException; use Aws\S3\Model\MultipartUpload\UploadBuilder; use Aws\S3\S3Client; $bucket = '*** Your Bucket Name ***'; $keyname = '*** Your Object Key ***'; // Instantiate the client. $s3 = S3Client::factory(); // Prepare the upload parameters. $uploader = UploadBuilder::newInstance() ->setClient($s3) ->setSource('/path/to/large/file.mov') ->setBucket($bucket) ->setKey($keyname) ->setMinPartSize(25 * 1024 * 1024) ->setOption('Metadata', array( 'param1' => 'value1', 'param2' => 'value2' )) ->setOption('ACL', 'public-read') ->setConcurrency(3) ->build(); // Perform the upload. Abort the upload if something goes wrong. try { $uploader->upload(); echo "Upload complete.\n"; } catch (MultipartUploadException $e) { $uploader->abort(); echo "Upload failed.\n"; echo $e->getMessage() . "\n"; }

Related Resources

On this page: