list_objects ( $bucket, $opt )

Gets a list of all Amazon S3 objects in the specified bucket.

NOTE: This method is paginated, and will not return more than max-keys keys. If you want to retrieve a list of all keys, you will need to make multiple calls to this function using the marker option to specify the pagination offset (the key of the last processed key—lexically ordered) and the IsTruncated response key to detect when all results have been processed. See: the S3 REST documentation for get_bucket for more information.

Access

public

Parameters

Parameter

Type

Required

Description

$bucket

string

Required

The name of the bucket to use.

$opt

array

Optional

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

  • delimiter - string - Optional - Keys that contain the same string between the prefix and the first occurrence of the delimiter will be rolled up into a single result element in the CommonPrefixes collection.
  • marker - string - Optional - Restricts the response to contain results that only occur alphabetically after the value of the marker.
  • max-keys - string - Optional - The maximum number of results returned by the method call. The returned list will contain no more results than the specified value, but may return fewer. The default value is 1000.
  • preauth - integer|string - Optional - Specifies that a presigned URL for this request should be returned. May be passed as a number of seconds since UNIX Epoch, or any string compatible with strtotime().
  • prefix - string - Optional - Restricts the response to contain results that begin only with the specified prefix.
  • 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. This toggle is useful for manually managed batch requests.

Returns

Type

Description

CFResponse

A CFResponse object containing a parsed HTTP response.

Examples

List all objects inside a bucket.

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

$response = $s3->list_objects($bucket);

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

List all objects inside a bucket that match the parameters given.

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

$response = $s3->list_objects($bucket, array(
	'prefix' => 'word/',
	'max-keys' => 1
));

// Success?
var_dump($response->isOK());
var_dump(count($response->body->Contents))
Result:
bool(true)
int(1)

List all objects inside a bucket that match the parameters given. Supports UTF-8 characters.

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

$response = $s3->list_objects($bucket, array(
	'delimiter' => '/',
	'marker' => 'mårkér wîth spåcés ånd întl'
));

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

Source

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

public function list_objects($bucket, $opt = null)
{
    if (!$opt) $opt = array();

    // Add this to our request
    $opt['verb'] = 'GET';

    foreach (array('delimiter', 'marker', 'max-keys', 'prefix') as $param)
    {
        if (isset($opt[$param]))
        {
            $opt['query_string'][$param] = $opt[$param];
            unset($opt[$param]);
        }
    }

    // Authenticate to S3
    return $this->authenticate($bucket, $opt);
}

Copyright © 2010–2013 Amazon Web Services, LLC


Feedback