create_bucket ( $bucket, $region, $acl, $opt )

Creates an Amazon S3 bucket.

Every object stored in Amazon S3 is contained in a bucket. Buckets partition the namespace of objects stored in Amazon S3 at the top level. in a bucket, any name can be used for objects. However, bucket names must be unique across all of Amazon S3.

Access

public

Parameters

Parameter

Type

Required

Description

$bucket

string

Required

The name of the bucket to create.

$region

string

Required

The preferred geographical location for the bucket. [Allowed values: AmazonS3::REGION_US_E1, AmazonS3::REGION_US_W1, AmazonS3::REGION_EU_W1, AmazonS3::REGION_APAC_SE1, AmazonS3::REGION_APAC_NE1]

$acl

string

Optional

The ACL settings for the specified object. Accepts any of the following constants: [Allowed values: AmazonS3::ACL_PRIVATE, AmazonS3::ACL_PUBLIC, AmazonS3::ACL_OPEN, AmazonS3::ACL_AUTH_READ, AmazonS3::ACL_OWNER_READ, AmazonS3::ACL_OWNER_FULL_CONTROL]. Alternatively, an array of associative arrays. Each associative array contains an id and a permission key. The default value is ACL_PRIVATE.

$opt

array

Optional

An associative array of parameters that can have the following keys:

  • curlopts - array - Optional - A set of values to pass directly into curl_setopt(), where the key is a pre-defined CURLOPT_* constant.
  • returnCurlHandle - boolean - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request.

Returns

Type

Description

CFResponse

A CFResponse object containing a parsed HTTP response.

Examples

Create a new bucket, setting the storage region.

// Instantiate the class
$s3 = new AmazonS3();
$bucket = 'my-bucket' . strtolower($s3->key);

$response = $s3->create_bucket($bucket, AmazonS3::REGION_US_STANDARD);

// Success?
var_dump($response->isOK());
Result:
bool(true)

Create a new bucket, setting the storage region and ACL settings.

// Instantiate the class
$s3 = new AmazonS3();
$bucket = 'my-bucket-us-east-acl' . strtolower($s3->key);

$response = $s3->create_bucket($bucket, AmazonS3::REGION_US_STANDARD, AmazonS3::ACL_PUBLIC);

// Success?
var_dump($response->isOK());
Result:
bool(true)

Create a new bucket, setting the storage region and using Grants for permissions.

// Instantiate the class
$s3 = new AmazonS3();
$bucket = 'my-bucket' . strtolower($s3->key);

$response = $s3->create_bucket($bucket, AmazonS3::REGION_US_STANDARD, array(
	array( 'id' => AmazonS3::USERS_AUTH,                                               'permission' => AmazonS3::GRANT_READ        ),
	array( 'id' => AmazonS3::USERS_AUTH,                                               'permission' => AmazonS3::GRANT_WRITE       ),
	array( 'id' => AmazonS3::USERS_ALL,                                                'permission' => AmazonS3::GRANT_WRITE       ),
	array( 'id' => 'my-email-address@domain.com',                                      'permission' => AmazonS3::GRANT_FULL_CONTROL),
	array( 'id' => '41f37e4803dbae41aa52290608a037dcf2309199b81c6257fe5570098b9e55a9', 'permission' => AmazonS3::GRANT_WRITE       ),
));

// Success?
var_dump($response->isOK());
Result:
bool(true)

See Also

Source

Method defined in services/s3.class.php | Toggle source view (67 lines) | View on GitHub

public function create_bucket($bucket, $region, $acl = self::ACL_PRIVATE, $opt = null)
{
    // If the bucket contains uppercase letters...
    if (preg_match('/[A-Z]/', $bucket))
    {
        // Throw a warning
        trigger_error('Since DNS-valid bucket names cannot contain uppercase characters, "' . $bucket . '" has been automatically converted to "' . strtolower($bucket) . '"', E_USER_WARNING);

        // Force the bucketname to lowercase
        $bucket = strtolower($bucket);
    }

    // Validate the S3 bucket name for creation
    if (!$this->validate_bucketname_create($bucket))
    {
        // @codeCoverageIgnoreStart
        throw new S3_Exception('"' . $bucket . '" is not DNS-valid (i.e., <bucketname>.s3.amazonaws.com), and cannot be used as an S3 bucket name. Review "Bucket Restrictions and Limitations" in the S3 Developer Guide for more information.');
        // @codeCoverageIgnoreEnd
    }

    if (!$opt) $opt = array();
    $opt['verb'] = 'PUT';
    $opt['headers'] = array(
        'Content-Type' => 'application/xml'
    );

    // Handle Access Control Lists. Can also be passed as an HTTP header.
    if (isset($acl))
    {
        if (is_array($acl))
        {
            $opt['headers'] = array_merge($opt['headers'], $this->generate_access_policy_headers($acl));
        }
        else
        {
            $opt['headers']['x-amz-acl'] = $acl;
        }
    }

    // Defaults
    $this->set_region($region); // Also sets path-style
    $xml = simplexml_load_string($this->base_location_constraint);

    switch ($region)
    {
        case self::REGION_US_E1: // Northern Virginia
            $opt['body'] = '';
            break;

        case self::REGION_EU_W1:    // Ireland
            $xml->LocationConstraint = 'EU';
            $opt['body'] = $xml->asXML();
            break;

        default:
            $xml->LocationConstraint = str_replace(array('s3-', '.amazonaws.com'), '', $region);
            $opt['body'] = $xml->asXML();
            break;
    }

    $response = $this->authenticate($bucket, $opt);

    // Make sure we're set back to DNS-style URLs
    $this->enable_path_style(false);

    return $response;
}

Copyright © 2010–2013 Amazon Web Services, LLC


Feedback