Manage a bucket

Last Updated: Aug 07, 2017

A bucket is a storage space on OSS and a management entity for billing, access control, logging and other advanced features.

Note: Complete code for the following scenarios can be found at GitHub.

Create a bucket

You can use OssClient::createBucket to create a new bucket:

  1. <?php
  2. /**
  3. * Create a bucket
  4. * The ACL specifies the access permission on the bucket, which may be private, public-read, or public-read-write.
  5. * The private permission indicates that only the bucket owner or the authorized user has the permission to read and write the bucket.
  6. * The three permissions respectively correspond to "OSSClient::OSS_ACL_TYPE_PRIVATE",
  7. * OssClient::OSS_ACL_TYPE_PUBLIC_READ,
  8. * OssClient::OSS_ACL_TYPE_PUBLIC_READ_WRITE
  9. *
  10. * @param OssClient $ossClient OSSClient instance
  11. * @param string $bucket Name of the bucket to be created
  12. * @return null
  13. */
  14. function createBucket($ossClient, $bucket)
  15. {
  16. try {
  17. $ossClient->createBucket($bucket, OssClient::OSS_ACL_TYPE_PRIVATE);
  18. } catch (OssException $e) {
  19. printf(__FUNCTION__ . ": FAILED\n");
  20. printf($e->getMessage() . "\n");
  21. return;
  22. }
  23. print(__FUNCTION__ . ": OK" . "\n");
  24. }

Note:

  • For Bucket naming rules, refer to the Naming Rules in Basic Concepts.
  • Because each bucket name must be globally unique, you should ensure that your bucket name is different from all others.
  • For more detailed interpretations of the bucket permissions, refer to Access Control.

Identify whether the bucket exists

You can determine whether a bucket exists using OssClient::doesBucketExist:

  1. /**
  2. * Determine whether the bucket exists
  3. *
  4. * @param OssClient $ossClient OssClient instance
  5. * @param string $bucket Bucket name
  6. */
  7. function doesBucketExist($ossClient, $bucket)
  8. {
  9. try {
  10. $res = $ossClient->doesBucketExist($bucket);
  11. } catch (OssException $e) {
  12. printf(__FUNCTION__ . ": FAILED\n");
  13. printf($e->getMessage() . "\n");
  14. return;
  15. }
  16. if ($res === true) {
  17. print(__FUNCTION__ . ": OK" . "\n");
  18. } else {
  19. print(__FUNCTION__ . ": FAILED" . "\n");
  20. }
  21. }

List all buckets of a user

You can use OssClient::listBuckets to list all the buckets of a user:

  1. <?php
  2. /**
  3. * List all buckets of a user
  4. *
  5. * @param OssClient $ossClient OssClient instance
  6. * @return null
  7. */
  8. function listBuckets($ossClient)
  9. {
  10. $bucketList = null;
  11. try{
  12. $bucketListInfo = $ossClient->listBuckets();
  13. } catch(OssException $e) {
  14. printf(__FUNCTION__ . ": FAILED\n");
  15. printf($e->getMessage() . "\n");
  16. return;
  17. }
  18. $bucketList = $bucketListInfo->getBucketList();
  19. foreach($bucketList as $bucket) {
  20. print($bucket->getLocation() . "\t" . $bucket->getName() . "\t" . $bucket->getCreatedate() . "\n");
  21. }
  22. }

Delete a bucket

You can use OssClient::deleteBucket to delete a bucket:

  1. <?php
  2. /**
  3. * Delete a bucket
  4. *
  5. * @param OssClient $ossClient OSSClient instance
  6. * @param string $bucket Name of the bucket to be deleted
  7. * @return null
  8. */
  9. function deleteBucket($ossClient, $bucket)
  10. {
  11. try{
  12. $ossClient->deleteBucket($bucket);
  13. } catch(OssException $e) {
  14. printf(__FUNCTION__ . ": FAILED\n");
  15. printf($e->getMessage() . "\n");
  16. return;
  17. }
  18. print(__FUNCTION__ . ": OK" . "\n");
  19. }

Notice:

  • A non-empty bucket (which contains objects or data parts from multipart upload) cannot be deleted.
  • To delete a non-empty bucket, you must first delete all objects and parts in it.

Set the ACL of a bucket

You can not only set the bucket ACL when creating a bucket, but also modify the bucket ACL according to your service requirements. Only the creator of the bucket has the permission to perform this operation. For more detailed interpretations of the bucket permissions, refer to Access Control.

There are currently three permissions available for a bucket:

Permission PHP SDK value
Private-read-write OssClient::OSS_ACL_TYPE_PRIVATE
Public-read and private-write OssClient::OSS_ACL_TYPE_PUBLIC_READ
Public-read-write OssClient::OSS_ACL_TYPE_PUBLIC_READ_WRITE

You can set the bucket access permission using OssClient::putBucketAcl:

  1. <?php
  2. /**
  3. * Configure the bucket ACL
  4. *
  5. * @param OssClient $ossClient OssClient instance
  6. * @param string $bucket Bucket name
  7. * @return null
  8. */
  9. function putBucketAcl($ossClient, $bucket)
  10. {
  11. $acl = OssClient::OSS_ACL_TYPE_PRIVATE;
  12. try {
  13. $ossClient->putBucketAcl($bucket, $acl);
  14. } catch (OssException $e) {
  15. printf(__FUNCTION__ . ": FAILED\n");
  16. printf($e->getMessage() . "\n");
  17. return;
  18. }
  19. print(__FUNCTION__ . ": OK" . "\n");
  20. }

Get the ACL of a bucket

You can set the bucket access permission using OssClient::getBucketAcl:

  1. <?php
  2. /**
  3. * Obtain the bucket ACL configuration
  4. *
  5. * @param OssClient $ossClient OssClient instance
  6. * @param string $bucket Bucket name
  7. * @return null
  8. */
  9. function getBucketAcl($ossClient, $bucket)
  10. {
  11. try {
  12. $res = $ossClient->getBucketAcl($bucket);
  13. } catch (OssException $e) {
  14. printf(__FUNCTION__ . ": FAILED\n");
  15. printf($e->getMessage() . "\n");
  16. return;
  17. }
  18. print(__FUNCTION__ . ": OK" . "\n");
  19. print('acl: ' . $res);
  20. }
Thank you! We've received your feedback.