get_object ( $bucket, $filename, $opt )

Gets the contents of an Amazon S3 object in the specified bucket.

The MD5 value for an object can be retrieved from the ETag HTTP header for any object that was uploaded with a normal PUT/POST. This value is incorrect for multipart uploads.

Access

public

Parameters

Parameter

Type

Required

Description

$bucket

string

Required

The name of the bucket to use.

$filename

string

Required

The file name for the object.

$opt

array

Optional

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

  • etag - string - Optional - The ETag header passed in from a previous request. If specified, request LastModified option must be specified as well. Will trigger a 304 Not Modified status code if the file hasn’t changed.
  • fileDownload - string|resource - Optional - The file system location to download the file to, or an open file resource. Must be a server-writable location.
  • headers - array - Optional - Standard HTTP headers to send along in the request. Accepts an associative array of key-value pairs.
  • lastmodified - string - Optional - The LastModified header passed in from a previous request. If specified, request ETag option must be specified as well. Will trigger a 304 Not Modified status code if the file hasn’t changed.
  • 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().
  • range - string - Optional - The range of bytes to fetch from the object. Specify this parameter when downloading partial bits or completing incomplete object downloads. The specified range must be notated with a hyphen (e.g., 0-10485759). Defaults to the byte range of the complete Amazon S3 object.
  • response - array - Optional - Allows adjustments to specific response headers. Pass an associative array where each key is one of the following: cache-control, content-disposition, content-encoding, content-language, content-type, expires. The expires value should use gmdate() and be formatted with the DATE_RFC2822 constant.
  • versionId - string - Optional - The version of the object to retrieve. Version IDs are returned in the x-amz-version-id header of any previous object-related request.
  • 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

Get an object.

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

$response = $s3->get_object($bucket, 'prefix with spaces/åéîøü/åéîøü/åéîøü with spaces.txt');

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

Get an object in pieces by specifying byte ranges.

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

// Empty response
$response = '';

// Read the first chunk
$response .= $s3->get_object($bucket, 'prefix with spaces/åéîøü/åéîøü/åéîøü with spaces.txt', array(
	'range' => '0-10'
))->body;

// Read the second chunk
$response .= $s3->get_object($bucket, 'prefix with spaces/åéîøü/åéîøü/åéîøü with spaces.txt', array(
	'range' => '11-21'
))->body;

// Success?
var_dump($response);
Result:
string(21) "This is my body text."

Conditionally get an object if the object has changed since we last pulled it.

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

// Get the file once
$response = $s3->get_object($bucket, 'prefix with spaces/åéîøü/åéîøü/åéîøü with spaces.txt');

// Store the ETag and Last-Modified headers
$etag = $response->header['etag'];
$last_modified = $response->header['last-modified'];

/*---- Later... ----*/

// Ask the server if the file has changed
$new_response = $s3->get_object($bucket, 'prefix with spaces/åéîøü/åéîøü/åéîøü with spaces.txt', array(
	'lastmodified' => $last_modified,
	'etag' => $etag
));

if ($new_response->isOK())
{
	// The server replied with "Yes, the file HAS changed. Here you go." (200)
	// Do something awesome with the updated data.
}
elseif ($new_response->isOK(304))
{
	// The server replied with "Dude, you've already got it." (304)
	// Do nothing because you're already awesome.
}

// Success?
var_dump($new_response->status);
Result:
int(304)

Get a specific version of an object.

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

// Get a specific version
$response = $s3->get_object($bucket, 'test1.txt', array(
	'versionId' => '0NNAq8PwvXvg8EfAYG9sSmwKTZeixZgZNE6PbodG8td0DJ3gVOmjI2Gh/oFnb0Ie='
));

// Success?
var_dump($response->isOK());
var_dump(strpos((string) $response->header['_info']['url'], 'versionId=' . $version_id) !== false);
Result:
bool(true)
bool(true)

Download an object to the file system.

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

$response = $s3->get_object($bucket, 'large_video.mov', array(
	'fileDownload' => 'large_video.mov'
));

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

Download to an open file resource.

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

$file_resource = fopen('large_video.mov', 'w+');

$response = $s3->get_object($bucket, 'large_video.mov', array(
	'fileDownload' => $file_resource
));

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

Override specific response headers.

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

$response = $s3->get_object($bucket, 'mårkér wîth spåcés ånd întl/åéîøü.txt', array(
	'response' => array(
		'content-type'     => 'text/plain',
		'content-language' => 'en-US',
		'expires'          => gmdate(DATE_RFC2822, strtotime('1 January 1980'))
	)
));

// Success?
var_dump($response->isOK());

// Check that we got back what we asked for
var_dump($response->header['content-language']);
var_dump($response->header['content-type']);
var_dump($response->header['expires']);
Result:
bool(true)
string(5) "en-US"
string(10) "text/plain"
string(31) "Tue, 01 Jan 1980 08:00:00 +0000"

Related Methods

Source

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

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

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

    if (!isset($opt['headers']) || !is_array($opt['headers']))
    {
        $opt['headers'] = array();
    }

    if (isset($opt['lastmodified']))
    {
        $opt['headers']['If-Modified-Since'] = $opt['lastmodified'];
    }

    if (isset($opt['etag']))
    {
        $opt['headers']['If-None-Match'] = $opt['etag'];
    }

    // Partial content range
    if (isset($opt['range']))
    {
        $opt['headers']['Range'] = 'bytes=' . $opt['range'];
    }

    // GET responses
    if (isset($opt['response']))
    {
        foreach ($opt['response'] as $key => $value)
        {
            $opt['response-' . $key] = $value;
            unset($opt['response'][$key]);
        }
    }

    // Authenticate to S3
    $this->parse_the_response = false;
    $response = $this->authenticate($bucket, $opt);
    $this->parse_the_response = true;

    return $response;
}

Copyright © 2010–2013 Amazon Web Services, LLC


Feedback