# Amazon::S3::Bucket - phpMan

## NAME
    [Amazon::S3::Bucket] - A container class for a S3 bucket and its contents.

## SYNOPSIS
      use [Amazon::S3];

      # creates bucket object (no "bucket exists" check)
      my $bucket = $s3->bucket("foo");

      # create resource with meta data (attributes)
      my $keyname = 'testing.txt';
      my $value   = 'T';
      $bucket->add_key(
          $keyname, $value,
          {   content_type        => 'text/plain',
              'x-amz-meta-colour' => 'orange',
          }
      );

      # list keys in the bucket
      $response = $bucket->list
          or die $s3->err . ": " . $s3->errstr;
      print $response->{bucket}."\n";
      for my $key (@{ $response->{keys} }) {
            print "\t".$key->{key}."\n";
      }

      # check if resource exists.
      print "$keyname exists\n" if $bucket->head_key($keyname);

      # delete key from bucket
      $bucket->delete_key($keyname);

## METHODS
  new
    Instaniates a new bucket object.

    Requires a hash containing two arguments:

    bucket
        The name (identifier) of the bucket.

    account
        The [S3::Amazon] object (representing the S3 account) this bucket is
        associated with.

    NOTE: This method does not check if a bucket actually exists. It simply
    instaniates the bucket.

    Typically a developer will not call this method directly, but work
    through the interface in [S3::Amazon] that will handle their creation.

  add_key
    Takes three positional parameters:

    key A string identifier for the resource in this bucket

    value
        A SCALAR string representing the contents of the resource.

    configuration
        A HASHREF of configuration data for this key. The configuration is
        generally the HTTP headers you want to pass the S3 service. The
        client library will add all necessary headers. Adding them to the
        configuration hash will override what the library would send and add
        headers that are not typically required for S3 interactions.

        In addition to additional and overridden HTTP headers, this HASHREF
        can have a "acl_short" key to set the permissions (access) of the
        resource without a separate call via "add_acl" or in the form of an
        XML document. See the documentation in "add_acl" for the values and
        usage.

    Returns a boolean indicating its success. Check "err" and "errstr" for
    error message if this operation fails.

  add_key_filename
    The method works like "add_key" except the value is assumed to be a
    filename on the local file system. The file will be streamed rather then
    loaded into memory in one big chunk.

  head_key $key_name
    Returns a configuration HASH of the given key. If a key does not exist
    in the bucket "undef" will be returned.

  get_key $key_name, [$method]
    Takes a key and an optional HTTP method and fetches it from S3. The
    default HTTP method is GET.

    The method returns "undef" if the key does not exist in the bucket and
    throws an exception (dies) on server errors.

    On success, the method returns a HASHREF containing:

    content_type
    etag
    value
    @meta

  get_key_filename $key_name, $method, $filename
    This method works like "get_key", but takes an added filename that the
    S3 resource will be written to.

  delete_key $key_name
    Permanently removes $key_name from the bucket. Returns a boolean value
    indicating the operations success.

  delete_bucket
    Permanently removes the bucket from the server. A bucket cannot be
    removed if it contains any keys (contents).

    This is an alias for "$s3-"delete_bucket($bucket)>.

  list
    List all keys in this bucket.

    See "list_bucket" in [Amazon::S3] for documentation of this method.

  list_all
    List all keys in this bucket without having to worry about 'marker'.
    This may make multiple requests to S3 under the hood.

    See "list_bucket_all" in [Amazon::S3] for documentation of this method.

  get_acl
    Retrieves the Access Control List (ACL) for the bucket or resource as an
    XML document.

    key The key of the stored resource to fetch. This parameter is optional.
        By default the method returns the ACL for the bucket itself.

  set_acl $conf
    Retrieves the Access Control List (ACL) for the bucket or resource.
    Requires a HASHREF argument with one of the following keys:

    acl_xml
        An XML string which contains access control information which
        matches Amazon's published schema.

    acl_short
        Alternative shorthand notation for common types of ACLs that can be
        used in place of a ACL XML document.

        According to the Amazon S3 API documentation the following
        recognized acl_short types are defined as follows:

        private
            Owner gets FULL_CONTROL. No one else has any access rights. This
            is the default.

        public-read
            Owner gets FULL_CONTROL and the anonymous principal is granted
            READ access. If this policy is used on an object, it can be read
            from a browser with no authentication.

        public-read-write
            Owner gets FULL_CONTROL, the anonymous principal is granted READ
            and WRITE access. This is a useful policy to apply to a bucket,
            if you intend for any anonymous user to PUT objects into the
            bucket.

        authenticated-read
            Owner gets FULL_CONTROL, and any principal authenticated as a
            registered Amazon S3 user is granted READ access.

    key The key name to apply the permissions. If the key is not provided
        the bucket ACL will be set.

    Returns a boolean indicating the operations success.

  get_location_constraint
    Returns the location constraint data on a bucket.

    For more information on location constraints, refer to the Amazon S3
    Developer Guide.

  err
    The S3 error code for the last error the account encountered.

  errstr
    A human readable error string for the last error the account
    encountered.

## SEE ALSO
    [Amazon::S3]

AUTHOR & COPYRIGHT
    Please see the [Amazon::S3] manpage for author, copyright, and license
    information.