get_object_list ( $bucket, $opt )

Gets a simplified list of Amazon S3 object file names contained in a bucket.

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:

<

ul>

  • 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 - integer - 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 less. A value of zero is treated as if you did not specify max-keys.
  • pcre - string - Optional - A Perl-Compatible Regular Expression (PCRE) to filter the names against. This is applied only AFTER any native Amazon S3 filtering from specified prefix, marker, max-keys, or delimiter values are applied.
  • 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.
  • Returns

    Type

    Description

    array

    The list of matching object names. If there are no results, the method will return an empty array.

    Examples

    Get a list of all filenames in a bucket.

    // Instantiate the class
    $s3 = new AmazonS3();
    $bucket = 'my-bucket' . strtolower($s3->key);
    
    $response = $s3->get_object_list($bucket);
    
    // Success?
    var_dump(gettype($response) === 'array');
    Result:
    bool(true)

    Get a list of all filenames in a bucket that match a given PCRE regular expression pattern.

    // Instantiate the class
    $s3 = new AmazonS3();
    $bucket = 'my-bucket' . strtolower($s3->key);
    
    // Get all filenames that match this pattern
    $response = $s3->get_object_list($bucket, array(
    	'pcre' => '/pdf/i'
    ));
    
    // Success?
    var_dump(gettype($response) === 'array');
    Result:
    bool(true)

    See Also

    Source

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

    public function get_object_list($bucket, $opt = null)
    {
        if ($this->use_batch_flow)
        {
            throw new S3_Exception(__FUNCTION__ . '() cannot be batch requested');
        }
    
        if (!$opt) $opt = array();
        unset($opt['returnCurlHandle']); // This would cause problems
    
        // Set some default values
        $pcre = isset($opt['pcre']) ? $opt['pcre'] : null;
        $max_keys = (isset($opt['max-keys']) && is_int($opt['max-keys'])) ? $opt['max-keys'] : null;
        $objects = array();
    
        if (!$max_keys)
        {
            // No max-keys specified. Get everything.
            do
            {
                $list = $this->list_objects($bucket, $opt);
                if (is_string($list->body))
                {
                    $list->body = new CFSimpleXML($list->body);
                }
                if ($keys = $list->body->query('descendant-or-self::Key')->map_string($pcre))
                {
                    $objects = array_merge($objects, $keys);
                }
    
                $body = (array) $list->body;
                $opt = array_merge($opt, array(
                    'marker' => (isset($body['Contents']) && is_array($body['Contents'])) ?
                        ((string) end($body['Contents'])->Key) :
                        ((string) $list->body->Contents->Key)
                ));
            }
            while ((string) $list->body->IsTruncated === 'true');
        }
        else
        {
            // Max-keys specified. Approximate number of loops and make the requests.
    
            $max_keys = $opt['max-keys'];
            $loops = ceil($max_keys / 1000);
    
            do
            {
                $list = $this->list_objects($bucket, $opt);
                if (is_string($list->body))
                {
                    $list->body = new CFSimpleXML($list->body);
                }
                $keys = $list->body->query('descendant-or-self::Key')->map_string($pcre);
    
                if ($count = count($keys))
                {
                    $objects = array_merge($objects, $keys);
    
                    if ($count < 1000)
                    {
                        break;
                    }
                }
    
                if ($max_keys > 1000)
                {
                    $max_keys -= 1000;
                }
    
                $body = (array) $list->body;
                $opt = array_merge($opt, array(
                    'max-keys' => $max_keys,
                    'marker' => (isset($body['Contents']) && is_array($body['Contents'])) ?
                        ((string) end($body['Contents'])->Key) :
                        ((string) $list->body->Contents->Key)
                ));
            }
            while (--$loops);
        }
    
        return $objects;
    }

    Copyright © 2010–2013 Amazon Web Services, LLC


    Feedback