generate_upload_parameters ( $bucket, $expires, $opt )

The POST operation adds an object to a specified bucket using HTML forms. POST is an alternate form of PUT that enables browser-based uploads as a way of putting objects in buckets. Parameters that are passed to PUT via HTTP headers are instead passed as form fields to POST in the multipart/form-data encoded message body. You must have WRITE access on a bucket to add an object to it. Amazon S3 never stores partial objects: if you receive a successful response, you can be confident the entire object was stored.

Access

public

Parameters

Parameter

Type

Required

Description

$bucket

string

Required

The name of the bucket to use.

$expires

string
integer

Optional

The point in time when the upload form field should expire. The default value is +1 hour.

$opt

array

Optional

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

  • acl - string - Optional - The access control setting to apply to the uploaded file. 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].
  • Cache-Control - string - Optional - The Cache-Control HTTP header value to apply to the uploaded file. To use a starts-with comparison instead of an equals comparison, prefix the value with a ^ (carat) character.
  • Content-Disposition - string - Optional - The Content-Disposition HTTP header value to apply to the uploaded file. To use a starts-with comparison instead of an equals comparison, prefix the value with a ^ (carat) character.
  • Content-Encoding - string - Optional - The Content-Encoding HTTP header value to apply to the uploaded file. To use a starts-with comparison instead of an equals comparison, prefix the value with a ^ (carat) character.
  • Content-Type - string - Optional - The Content-Type HTTP header value to apply to the uploaded file. The default value is application/octet-stream. To use a starts-with comparison instead of an equals comparison, prefix the value with a ^ (carat) character.
  • Expires - string - Optional - The Expires HTTP header value to apply to the uploaded file. To use a starts-with comparison instead of an equals comparison, prefix the value with a ^ (carat) character.
  • key - string - Optional - The location where the file should be uploaded to. The default value is ${filename}.
  • success_action_redirect - string - Optional - The URI for Amazon S3 to redirect to upon successful upload.
  • success_action_status - integer - Optional - The status code for Amazon S3 to return upon successful upload.
  • x-amz-server-side-encryption - string - Optional - The server-side encryption mechanism to use. [Allowed values: AES256].
  • x-amz-storage-class - string - Optional - The storage setting to apply to the object. [Allowed values: AmazonS3::STORAGE_STANDARD, AmazonS3::STORAGE_REDUCED]. The default value is AmazonS3::STORAGE_STANDARD.
  • x-amz-website-redirect-location - string - Optional - The URI to send an HTTP 301 redirect to when accessing this object. Value must be prefixed either /, http:// or https://.
  • x-amz-meta-* - mixed - Optional - Any custom meta tag that should be set to the object.

Returns

Type

Description

array

An array of fields that can be converted into markup.

Examples

Generate the parameters for a browser-based POST upload.

This example shows how to construct the data object that is then used to generate HTML.

$upload = new S3BrowserUpload();

// Generate the parameters for the upload.
$html_parameters = $upload->generate_upload_parameters('my-upload-bucket', '15 minutes', array(

	// Set permissions to private.
	'acl' => AmazonS3::ACL_PRIVATE,

	// Set various HTTP headers on the uploaded file.
	'Content-Disposition' => 'attachment; filename=information.txt',
	'Content-Encoding' => 'gzip',
	'Content-Type' => '^text/',
	'Expires' => gmdate(DATE_RFC1123, strtotime('January 1, 1970, midnight GMT')), // Format for the HTTP Expires header

	// The S3 Key to upload to. ${filename} is an S3 variable that equals the name of the file being uploaded.
	// We're also using PHP's built-in Filter extension in this example.
	'key' => '^user/' . filter_var($_POST['user_id'], FILTER_VALIDATE_INT) . '/${filename}',

	// Where should S3 redirect to after the upload completes? The current page.
	'success_action_redirect' => S3BrowserUpload::current_uri(),

	// Status code to send back on success. This is primarily to work around issues in Adobe® Flash®.
	'success_action_status' => 201,

	// Use reduced redundancy storage.
	'x-amz-storage-class' => AmazonS3::STORAGE_REDUCED
));



<form action="<?= $html_parameters['form']['action'] "
      method="<?= $html_parameters['form']['method'] "
      enctype="<?= $html_parameters['form']['enctype'] ">

<? foreach ($html_parameters['inputs'] as $name => $value): 
<input type="hidden" name="<?= $name; " value="<?= $value; ">
<? endforeach; 

<input type="file" name="file">
<input type="submit" name="upload" value="Upload">
</form>

See Also

Source

Method defined in extensions/s3browserupload.class.php | Toggle source view (81 lines) | View on GitHub

public function generate_upload_parameters($bucket, $expires = '+1 hour', $opt = null)
{
    if (!$opt) $opt = array();

    // Policy document
    $policy = array(
        'conditions' => array(
            array('bucket' => $bucket),
        )
    );

    // Basic form
    $form = array();
    $form['form'] = array(
        'action' => $bucket . '.s3.amazonaws.com',
        'method' => 'POST',
        'enctype' => 'multipart/form-data'
    );

    // Inputs
    $form['inputs'] = array(
        'AWSAccessKeyId' => $this->key
    );

    // Expires
    if ($expires)
    {
        if (is_numeric($expires))
        {
            $expires = gmdate('j M Y, g:i a Z', (integer) $expires);
        }

        $expires = $this->util->convert_date_to_iso8601($expires);
        $policy['expiration'] = (string) $expires;
    }

    // Default values
    if (!isset($opt['key']))
    {
        $opt['key'] = '${filename}';
    }

    // Success Action Status
    if (isset($opt['success_action_status']) && !empty($opt['success_action_status']))
    {
        $form['inputs']['success_action_status'] = (string) $opt['success_action_status'];
        $policy['conditions'][] = array(
            'success_action_status' => (string) $opt['success_action_status']
        );
        unset($opt['success_action_status']);
    }

    // Other parameters
    foreach ($opt as $param_key => $param_value)
    {
        if ($param_value[0] === '^')
        {
            $form['inputs'][$param_key] = substr((string) $param_value, 1);
            $param_value = preg_replace('/\$\{(\w*)\}/', '', (string) $param_value);
            $policy['conditions'][] = array('starts-with', '$' . $param_key, (substr((string) $param_value, 1) ? substr((string) $param_value, 1) : ''));
        }
        else
        {
            $form['inputs'][$param_key] = (string) $param_value;
            $policy['conditions'][] = array(
                $param_key => (string) $param_value
            );
        }
    }

    // Add policy
    $json_policy = json_encode($policy);
    $json_policy_b64 = base64_encode($json_policy);
    $form['inputs']['policy'] = $json_policy_b64;
    $form['metadata']['json_policy'] = $json_policy;

    // Add signature
    $form['inputs']['signature'] = base64_encode(hash_hmac('sha1', $json_policy_b64, $this->secret_key, true));

    return $form;
}

Copyright © 2010–2013 Amazon Web Services, LLC


Feedback