edit-icon download-icon

Upload objects

Last Updated: Dec 26, 2017

In the OSS, objects are the basic data units for user operation. OSS PHP SDK provides a variety of object uploading interfaces. You can upload an object through any of the following methods:

  • String upload
  • Object upload
  • Append upload
  • Multipart upload

The size of objects for string upload, object upload, and append upload operations must not exceed 5 GB. When the object size is large, use the multipart upload method. The size of parts for multipart upload may not exceed 48.8 TB.

String upload

The following code uploads the content of a specified string to an object:

  1. <?php
  2. /**
  3. * Upload string value as the object content
  4. *
  5. * @param OssClient $ossClient OSSClient instance
  6. * @param string $bucket Bucket name
  7. * @return null
  8. */
  9. function putObject($ossClient, $bucket)
  10. {
  11. $object = "oss-php-sdk-test/upload-test-object-name.txt";
  12. $content = file_get_contents(__FILE__);
  13. try{
  14. $ossClient->putObject($bucket, $object, $content);
  15. } catch(OssException $e) {
  16. printf(__FUNCTION__ . ": FAILED\n");
  17. printf($e->getMessage() . "\n");
  18. return;
  19. }
  20. print(__FUNCTION__ . ": OK" . "\n");
  21. }

Upload a local file

The following code uploads a specified local file to an object in a bucket:

  1. <?php
  2. /**
  3. * Upload the content of a specified local file
  4. *
  5. * @param OssClient $ossClient OSSClient instance
  6. * @param string $bucket Bucket name
  7. * @return null
  8. */
  9. function uploadFile($ossClient, $bucket)
  10. {
  11. $object = "oss-php-sdk-test/upload-test-object-name.txt";
  12. $filePath = __FILE__;
  13. try{
  14. $ossClient->uploadFile($bucket, $object, $filePath);
  15. } catch(OssException $e) {
  16. printf(__FUNCTION__ . ": FAILED\n");
  17. printf($e->getMessage() . "\n");
  18. return;
  19. }
  20. print(__FUNCTION__ . ": OK" . "\n");
  21. }

Notice: When you upload a file using the preceding code, make sure that the file size does not exceed 5 GB. If the file exceeds 5 GB, upload it through multipart upload.

Append upload

Objects created by simple upload, multipart upload and resumable upload operations are all Normal objects which have fixed content after the upload. They can only be read, but cannot be modified. If the object content changes, you can only upload an object of the same name to overwrite the old content. This is a major difference between OSS and general file systems. This feature leads to inconvenience in many application scenarios, typical ones being video monitoring and live video fields, since video data is constantly produced in real time.

OSS allows you to directly append content to the end of an object using the Append Object method. Objects uploaded by this method are Appendable objects, while objects uploaded by other methods are Normal objects. The data appended is instantly readable.

Append upload string

The following code uploads a specified string to an object:

  1. <?php
  2. /**
  3. * Append upload of strings
  4. *
  5. * @param OssClient $ossClient OSSClient instance
  6. * @param string $bucket Bucket name
  7. * @return null
  8. */
  9. function putObject($ossClient, $bucket)
  10. {
  11. $object = "oss-php-sdk-test/append-test-object-name.txt";
  12. $content_array = array('Hello OSS', 'Hi OSS', 'OSS OK');
  13. try{
  14. $position = $this->ossClient->appendObject($this->bucket, $object, $content_array[0], 0);
  15. $position = $this->ossClient->appendObject($this->bucket, $object, $content_array[1], $position);
  16. $position = $this->ossClient->appendObject($this->bucket, $object, $content_array[2], $position);
  17. } catch(OssException $e) {
  18. printf(__FUNCTION__ . ": FAILED\n");
  19. printf($e->getMessage() . "\n");
  20. return;
  21. }
  22. print(__FUNCTION__ . ": OK" . "\n");
  23. }

Append upload an object

The following code uploads a local file to the OSS object through the append load approach:

  1. /**
  2. * Append upload of objects
  3. *
  4. * @param OssClient $ossClient OSSClient instance
  5. * @param string $bucket Bucket name
  6. * @return null
  7. */
  8. function putObject($ossClient, $bucket)
  9. {
  10. $object = "oss-php-sdk-test/append-test-object-name.txt";
  11. try{
  12. $position = $this->ossClient->appendFile($this->bucket, $object, __FILE__, 0);
  13. $position = $this->ossClient->appendFile($this->bucket, $object, __FILE__, $position);
  14. } catch(OssException $e) {
  15. printf(__FUNCTION__ . ": FAILED\n");
  16. printf($e->getMessage() . "\n");
  17. return;
  18. }
  19. print(__FUNCTION__ . ": OK" . "\n");
  20. }

Notice:

  • The maximum number of append uploads is not limited. The maximum object size is 5 GB. You can use multipart upload to upload larger files.
  • Objects uploaded by Append Object do not currently support copyObject operations.

Multipart upload

In addition to the PutObject interface, OSS also provides the Multipart Upload mode for you to upload files.You can apply the Multipart Upload mode in the following scenarios (but not limited to the following):

  • Resumable upload is required.
  • Upload an object larger than 100 MB.
  • The network conditions are poor and the OSS server is frequently disconnected.
  • The size of the object to be uploaded is unknown.

Note: Complete multipart upload code can be found at GitHub.

Upload local files in multiple parts

The following code uses an encapsulated easy-to-use interface to upload a file through multipart upload:

  1. <?php
  2. /**
  3. * Upload a file through multipart upload
  4. *
  5. * @param OssClient $ossClient OSSClient instance
  6. * @param string $bucket Bucket name
  7. * @return null
  8. */
  9. function multiuploadFile($ossClient, $bucket)
  10. {
  11. $object = "test/multipart-test.txt";
  12. $file = __FILE__;
  13. try{
  14. $ossClient->multiuploadFile($bucket, $object, $file);
  15. } catch(OssException $e) {
  16. printf(__FUNCTION__ . ": FAILED\n");
  17. printf($e->getMessage() . "\n");
  18. return;
  19. }
  20. print(__FUNCTION__ . ": OK" . "\n");
  21. }

Upload a local directory through multipart upload

The following code uses an encapsulated easy-to-use interface to upload a directory through multipart upload:

  1. <?php
  2. /**
  3. * Upload files by directory
  4. *
  5. * @param OssClient $ossClient OssClient
  6. * @param string $bucket Bucket name
  7. *
  8. */
  9. function uploadDir($ossClient, $bucket) {
  10. $localDirectory = ".";
  11. $prefix = "samples/codes";
  12. try {
  13. $ossClient->uploadDir($bucket, $prefix, $localDirectory);
  14. } catch(OssException $e) {
  15. printf(__FUNCTION__ . ": FAILED\n");
  16. printf($e->getMessage() . "\n");
  17. return;
  18. }
  19. printf(__FUNCTION__ . ": completeMultipartUpload OK\n");
  20. }

Multipart upload with the original interface

The general multipart upload process is as follows:

  • Initialize a multipart upload task (InitiateMultipartUpload)
  • Upload the parts one by one in sequence or in parallel (UploadPart)
  • Complete the multipart upload (CompleteMultipartUpload) or cancel the multipart upload (AbortMultipartUpload)

The following example shows how to complete a multipart upload task in steps using the original API. If you want to perform resumable upload or other advanced operations, see the following code:

  1. <?php
  2. /**
  3. * Use basic APIs to perform multipart upload step by step
  4. *
  5. * @param OssClient $ossClient OSSClient instance
  6. * @param string $bucket Bucket name
  7. * @throws OssException
  8. */
  9. function putObjectByRawApis($ossClient, $bucket)
  10. {
  11. $object = "test/multipart-test.txt";
  12. /**
  13. * Step 1. Initialize a multipart upload task, that is, initialize the upload multipart, and obtain an UploadID.
  14. */
  15. try{
  16. $uploadId = $ossClient->initiateMultipartUpload($bucket, $object);
  17. } catch(OssException $e) {
  18. printf(__FUNCTION__ . ": initiateMultipartUpload FAILED\n");
  19. printf($e->getMessage() . "\n");
  20. return;
  21. }
  22. print(__FUNCTION__ . ": initiateMultipartUpload OK" . "\n");
  23. /*
  24. * Step 2. Upload parts.
  25. */
  26. $partSize = 10 * 1024 * 1024;
  27. $uploadFile = __FILE__;
  28. $uploadFileSize = filesize($uploadFile);
  29. $pieces = $ossClient->generateMultiuploadParts($uploadFileSize, $partSize);
  30. $responseUploadPart = array();
  31. $uploadPosition = 0;
  32. $isCheckMd5 = true;
  33. foreach ($pieces as $i => $piece) {
  34. $fromPos = $uploadPosition + (integer)$piece[$ossClient::OSS_SEEK_TO];
  35. $toPos = (integer)$piece[$ossClient::OSS_LENGTH] + $fromPos - 1;
  36. $upOptions = array(
  37. $ossClient::OSS_FILE_UPLOAD => $uploadFile,
  38. $ossClient::OSS_PART_NUM => ($i + 1),
  39. $ossClient::OSS_SEEK_TO => $fromPos,
  40. $ossClient::OSS_LENGTH => $toPos - $fromPos + 1,
  41. $ossClient::OSS_CHECK_MD5 => $isCheckMd5,
  42. );
  43. if ($isCheckMd5) {
  44. $contentMd5 = OssUtil::getMd5SumForFile($uploadFile, $fromPos, $toPos);
  45. $upOptions[$ossClient::OSS_CONTENT_MD5] = $contentMd5;
  46. }
  47. //2. Upload each part to the OSS
  48. try {
  49. $responseUploadPart[] = $ossClient->uploadPart($bucket, $object, $uploadId, $upOptions);
  50. } catch(OssException $e) {
  51. printf(__FUNCTION__ . ": initiateMultipartUpload, uploadPart - part#{$i} FAILED\n");
  52. printf($e->getMessage() . "\n");
  53. return;
  54. }
  55. printf(__FUNCTION__ . ": initiateMultipartUpload, uploadPart - part#{$i} OK\n");
  56. }
  57. $uploadParts = array();
  58. foreach ($responseUploadPart as $i => $eTag) {
  59. $uploadParts[] = array(
  60. 'PartNumber' => ($i + 1),
  61. 'ETag' => $eTag,
  62. );
  63. }
  64. /**
  65. * Step 3. Complete the upload
  66. */
  67. try {
  68. $ossClient->completeMultipartUpload($bucket, $object, $uploadId, $uploadParts);
  69. } catch(OssException $e) {
  70. printf(__FUNCTION__ . ": completeMultipartUpload FAILED\n");
  71. printf($e->getMessage() . "\n");
  72. return;
  73. }
  74. printf(__FUNCTION__ . ": completeMultipartUpload OK\n");
  75. }

Notice:

  • The preceding process consists of three steps: 1. initiate; 2. uploadPart; 3. complete.
  • When you use the UploadPart method to upload each part (in Step 2), note the following point:
    • The UploadPart method requires that all parts except the last one be larger than or equal to 100 KB. However, the Upload Part interface does not check the uploaded part size immediatelybecause it does not know whether the part is the last one. It checks the size only when multipart upload is completed.
  • OSS returns the MD5 value of the data part that the server receives to the UploadPart interface of the OSSClient.
  • The part number ranges from 1 to 10,000. If the part number exceeds this range, the OSS returns the InvalidArgument error code.
  • When each part is uploaded, the stream is directed to the start point of the uploaded part.
  • After each part is uploaded, the returned result of the OSS contains a PartETag object, which combines the ETag and PartNumber of the uploaded part. You must save the PartETag because it is used to complete the multipart upload task (Step 3). For operation details, see the preceding code.
  • After you initialize the multipart upload task or upload some parts, you can use the abortMultipartUpload interface to cancel the multipart upload event. - When a multipart upload task is canceled, you cannot use the Upload ID to perform any operations and the uploaded parts are deleted.

View uploaded parts

The view uploaded parts operation can list all successfully uploaded parts mapped to a specified Upload ID.

You can view uploaded parts of an upload task using the following code:

  1. /**
  2. * View uploaded parts
  3. *
  4. * @param OssClient $ossClient OSSClient instance
  5. * @param string $bucket Bucket name
  6. * @param string $uploadId upload Id
  7. * @return null
  8. */
  9. function putObject($ossClient, $bucket, $uploadId)
  10. {
  11. $object = "oss-php-sdk-test/upload-test-object-name.txt";
  12. try{
  13. $listPartsInfo = $ossClient->listParts($bucket, $object, $upload_id);
  14. foreach ($listPartsInfo->getListPart() as $partInfo) {
  15. print($partInfo->getPartNumber() . "\t" . $partInfo->getSize() . "\t" . $partInfo->getETag() . "\t" . $partInfo->getLastModified() . "\n");
  16. }
  17. } catch(OssException $e) {
  18. printf(__FUNCTION__ . ": FAILED\n");
  19. printf($e->getMessage() . "\n");
  20. return;
  21. }
  22. print(__FUNCTION__ . ": OK" . "\n");
  23. }

View ongoing multipart upload tasks

The following code lists ongoing multipart upload tasks:

  1. <?php
  2. /**
  3. * Get the list of currently unfinished multipart upload tasks
  4. *
  5. * @param $ossClient OssClient
  6. * @param $bucket string
  7. */
  8. function listMultipartUploads($ossClient, $bucket) {
  9. $options = array(
  10. 'delimiter' => '/',
  11. 'max-uploads' => 100,
  12. 'key-marker' => '',
  13. 'prefix' => '',
  14. 'upload-id-marker' => ''
  15. );
  16. try {
  17. $listMultipartUploadInfo = $ossClient->listMultipartUploads($bucket, $options);
  18. } catch(OssException $e) {
  19. printf(__FUNCTION__ . ": listMultipartUploads FAILED\n");
  20. printf($e->getMessage() . "\n");
  21. return;
  22. }
  23. printf(__FUNCTION__ . ": listMultipartUploads OK\n");
  24. $listUploadInfo = $listMultipartUploadInfo->getUploads();
  25. var_dump($listUploadInfo);
  26. }

The parameters of $options in the preceding code are described as follows:

Key Description
Delimiter A character used to group object names. All the objects whose names contain the specified prefix and appear before the delimiter for the first time form a group of elements called CommonPrefixes.
key-marker The key-marker is used with the upload-id-marker parameter to specify the start point of the returned results.
max-uploads Specify the maximum number of multipart upload tasks returned for one request. If this parameter is not specified, the default value 1,000 applies. The max-uploads value cannot exceed 1,000.
prefix The keys of returned objects must use the prefix. Note that when you make a query using the prefix, the returned key still contains the prefix.
upload-id-marker The upload-id-marker is used with the key-marker parameter to specify the start point of the returned results.

Set object metadata (Object Meta)

Object Meta describes the attributes of objects uploaded to the OSS. These attributes come in two types: HTTP standard attributes (HTTP Headers) and user-defined metainformation (User Meta). The object meta information can be set during various upload modes (string upload, object upload, append upload and multipart upload) or object copy operations. The names of metainformation are case-insensitive. For more information on object metadata, see Object Meta.

Set the HTTP header

The OSS allows you to customize HTTP headers. For more on HTTP headers, see RFC2616. Several frequently-used HTTP headers are described as follows:

Name Description Default value
Content-MD5 Object data verification. After this value is set, the OSS enables the MD5 verification on the object content and compare the MD5 you provide with the MD5 of the object. An error is thrown if any inconsistency is found None
Content-Type The object MIME. It defines the object type and webpage encoding and decides the form and encoding used by the browser to read objects. If not specified, the object MIME is generated based on the key or object name extension. If no extension is available, the default value applies application/octet-stream
Content-Disposition It instructs the MIME user proxy how to display, open, or download the attached object and the object name None
Content-Length The length of the uploaded object. The excessive length of the stream/object is truncated. If the data falls short of the length, the actual data length applies The time length of the stream/object
Expires The expiration time of cache. It is not used in the OSS. The time format is in GMT None
Cache-Control It specifies the cache action of the webpage when the object is downloaded None

The following code sets the object HTTP headers during uploads:

  1. /**
  2. * Set the metadata of the object during upload
  3. *
  4. * @param OssClient $ossClient OSSClient instance
  5. * @param string $bucket Bucket name
  6. * @return null
  7. */
  8. function putObject($ossClient, $bucket)
  9. {
  10. $object = "oss-php-sdk-test/upload-test-object-name.txt";
  11. $content = file_get_contents(__FILE__);
  12. $options = array(
  13. OssClient::OSS_HEADERS => array(
  14. 'Expires' => '2012-10-01 08:00:00',
  15. 'Content-Disposition' => 'attachment; filename="xxxxxx"',
  16. ));
  17. try{
  18. $ossClient->putObject($bucket, $object, $content, $options);
  19. } catch(OssException $e) {
  20. printf(__FUNCTION__ . ": FAILED\n");
  21. printf($e->getMessage() . "\n");
  22. return;
  23. }
  24. print(__FUNCTION__ . ": OK" . "\n");
  25. }

Notice:

  • You can modify the object type by setting the object Content-Type.
  • You can control the object download behaviors by setting the object Content-Disposition.
  • The putObject, uploadFile, appendObject, appendFile, multiuploadFile, and initiateMultipartUpload operations support setting the HTTP header.

User Meta

OSS allows you to customize object meta information to describe objects.

The following code sets the object user meta during uploads:

  1. <?php
  2. /**
  3. * Set the user meta of the object during uploads
  4. *
  5. * @param OssClient $ossClient OSSClient instance
  6. * @param string $bucket Bucket name
  7. * @return null
  8. */
  9. function putObject($ossClient, $bucket)
  10. {
  11. $object = "oss-php-sdk-test/upload-test-object-name.txt";
  12. $content = file_get_contents(__FILE__);
  13. $options = array(OssClient::OSS_HEADERS => array(
  14. 'x-oss-meta-self-define-title' => 'user define meta info',
  15. ));
  16. try{
  17. $ossClient->putObject($bucket, $object, $content, $options);
  18. } catch(OssException $e) {
  19. printf(__FUNCTION__ . ": FAILED\n");
  20. printf($e->getMessage() . "\n");
  21. return;
  22. }
  23. print(__FUNCTION__ . ": OK" . "\n");
  24. }

Note:

  • You can get the object meta information through OssClient::getObjectMeta.
  • The User Meta name is case-insensitive. For instance, if the meta information is set to x-oss-meta-name, you only need to read the parameter named x-oss-meta-name.
  • An object may contain multiple meta data items, but the total size of meta data must not exceed 8 KB.
  • The putObject, uploadFile, appendObject, appendFile, multiuploadFile, and initiateMultipartUpload operations support setting the user meta information.

Use MD5 for verification during uploads

The OSS supports MD5 verification to guarantee the consistency between the data sent by the PHP SDK and the data received on the OSS server. MD5 verification is disabled by default during object uploads (string upload, object upload, append upload and multipart upload). If you want to enable the MD5 verification, configure the settings in the options for uploading objects.

The following code enables the MD5 verification during uploads:

  1. <?php
  2. /**
  3. * Enable MD5 verification during uploads
  4. *
  5. * @param OssClient $ossClient OSSClient instance
  6. * @param string $bucket Bucket name
  7. * @return null
  8. */
  9. function putObject($ossClient, $bucket)
  10. {
  11. $object = "oss-php-sdk-test/upload-test-object-name.txt";
  12. $options = array(OssClient::OSS_CHECK_MD5 => true);
  13. try{
  14. $ossClient->uploadFile($bucket, $object, __FILE__, $options);
  15. } catch(OssException $e) {
  16. printf(__FUNCTION__ . ": FAILED\n");
  17. printf($e->getMessage() . "\n");
  18. return;
  19. }
  20. print(__FUNCTION__ . ": OK" . "\n");
  21. }

Notice:

  • MD5 verification may lead to compromised performance.
  • The putObject, uploadFile, appendObject, appendFile, and multiuploadFile operations support selection of OSS_CHECK_MD5.
Thank you! We've received your feedback.