Copies an Amazon S3 object to a new location, whether in the same Amazon S3 region, bucket, or otherwise.
NOTE: Object redirect locations are not carried over when an object is copied.
Access
Parameters
Parameter |
Type |
Required |
Description |
$source
|
array
|
Required
|
The bucket and file name to copy from. The following keys must be set:
bucket - string - Required - Specifies the name of the bucket containing the source object.filename - string - Required - Specifies the file name of the source object to copy. |
$dest
|
array
|
Required
|
The bucket and file name to copy to. The following keys must be set:
bucket - string - Required - Specifies the name of the bucket to copy the object to.filename - string - Required - Specifies the file name to copy the object to. |
$opt
|
array
|
Optional
|
An associative array of parameters that can have the following keys:
acl - string - Optional - The ACL settings for the specified object. [Allowed values: AmazonS3::ACL_PRIVATE , AmazonS3::ACL_PUBLIC , AmazonS3::ACL_OPEN , AmazonS3::ACL_AUTH_READ , AmazonS3::ACL_OWNER_READ , AmazonS3::ACL_OWNER_FULL_CONTROL ]. Alternatively, an array of associative arrays. Each associative array contains an id and a permission key. The default value is ACL_PRIVATE .encryption - string - Optional - The algorithm to use for encrypting the object. [Allowed values: AES256 ]storage - string - Optional - Whether to use Standard or Reduced Redundancy storage. [Allowed values: AmazonS3::STORAGE_STANDARD , AmazonS3::STORAGE_REDUCED ]. The default value is STORAGE_STANDARD .versionId - string - Optional - The version of the object to copy. Version IDs are returned in the x-amz-version-id header of any previous object-related request.ifMatch - string - Optional - The ETag header from a previous request. Copies the object if its entity tag (ETag) matches the specified tag; otherwise, the request returns a 412 HTTP status code error (precondition failed). Used in conjunction with ifUnmodifiedSince .ifUnmodifiedSince - string - Optional - The LastModified header from a previous request. Copies the object if it hasn’t been modified since the specified time; otherwise, the request returns a 412 HTTP status code error (precondition failed). Used in conjunction with ifMatch .ifNoneMatch - string - Optional - The ETag header from a previous request. Copies the object if its entity tag (ETag) is different than the specified ETag; otherwise, the request returns a 412 HTTP status code error (failed condition). Used in conjunction with ifModifiedSince .ifModifiedSince - string - Optional - The LastModified header from a previous request. Copies the object if it has been modified since the specified time; otherwise, the request returns a 412 HTTP status code error (failed condition). Used in conjunction with ifNoneMatch .headers - array - Optional - Standard HTTP headers to send along in the request. Accepts an associative array of key-value pairs.meta - array - Optional - Associative array of key-value pairs. Represented by x-amz-meta-: Any header starting with this prefix is considered user metadata. It will be stored with the object and returned when you retrieve the object. The total size of the HTTP request, not including the body, must be less than 4 KB.metadataDirective - string - Optional - Accepts either COPY or REPLACE. You will likely never need to use this, as it manages itself with no issues.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
Examples
Copy an object by specifying a source and a destination.
// Instantiate the class
$s3 = new AmazonS3();
$bucket = 'my-bucket' . strtolower($s3->key);
$response = $s3->copy_object(
array( // Source
'bucket' => $bucket,
'filename' => 'test1.txt'
),
array( // Destination
'bucket' => $bucket,
'filename' => 'test2.txt'
)
);
// Success?
var_dump($response->isOK());
Result:
bool(true)
Copy an object, setting the new object to use reduced redundancy.
// Instantiate the class
$s3 = new AmazonS3();
$bucket = 'my-bucket' . strtolower($s3->key);
$response = $s3->copy_object(
array( // Source
'bucket' => $bucket,
'filename' => 'prefix/one/two/test1.txt'
),
array( // Destination
'bucket' => $bucket,
'filename' => 'prefix/one/two/test2.txt'
),
array( // Optional parameters
'storage' => AmazonS3::STORAGE_REDUCED
)
);
// Success?
var_dump($response->isOK());
Result:
bool(true)
Copy an object, setting other headers and settings.
// Instantiate the class
$s3 = new AmazonS3();
$bucket = 'my-bucket' . strtolower($s3->key);
$response = $s3->copy_object(
array( // Source
'bucket' => $bucket,
'filename' => 'test1.txt'
),
array( // Destination
'bucket' => $bucket,
'filename' => 'test2.txt'
),
array( // Optional parameters
'acl' => AmazonS3::ACL_PUBLIC,
'meta' => array(
'x-fake-header' => 'something awesome is happening'
)
)
);
// Success?
var_dump($response->isOK());
Result:
bool(true)
Copy a specific version of an object.
Note: Requires versioning to be enabled on a bucket first.
// Instantiate the class
$s3 = new AmazonS3();
$bucket = 'my-bucket' . strtolower($s3->key);
$response = $s3->copy_object(
array( // Source
'bucket' => $bucket,
'filename' => 'test1.txt'
),
array( // Destination
'bucket' => $bucket,
'filename' => 'test-version.txt'
),
array( // Optional parameters
'versionId' => '0NNAq8PwvXvg8EfAYG9sSmwKTZeixZgZNE6PbodG8td0DJ3gVOmjI2Gh/oFnb0Ie='
)
);
// Success?
var_dump($response->isOK());
Result:
bool(true)
Conditionally copy an object — only if the original is newer than what we have.
// Instantiate the class
$s3 = new AmazonS3();
$bucket = 'my-bucket' . strtolower($s3->key);
// Store the `etag` and `last-modified` headers the first time we pull down an object.
$head = $s3->get_object_headers($bucket, 'test1.txt');
$etag = $head->header['etag'];
$last_modified = $head->header['last-modified'];
/*---- Later... ----*/
// Copy, only if the original is newer than what we have
$response = $s3->copy_object(
array( // Source
'bucket' => $bucket,
'filename' => 'test1.txt'
),
array( // Destination
'bucket' => $bucket,
'filename' => 'test2.txt'
),
array( // Conditional Copy
'ifNoneMatch' => $etag,
'ifModifiedSince' => $last_modified
)
);
// Success?
var_dump($response->isOK());
Result:
bool(true)
Related Methods
See Also
Source
Method defined in services/s3.class.php | Toggle source view (100 lines) | View on GitHub
public function copy_object($source, $dest, $opt = null)
{
if (!$opt) $opt = array();
$batch = array();
// Add this to our request
$opt['verb'] = 'PUT';
$opt['resource'] = $dest['filename'];
$opt['body'] = '';
// Handle copy source
if (isset($source['bucket']) && isset($source['filename']))
{
$opt['headers']['x-amz-copy-source'] = '/' . $source['bucket'] . '/' . rawurlencode($source['filename'])
. (isset($opt['versionId']) ? ('?' . 'versionId=' . rawurlencode($opt['versionId'])) : ''); // Append the versionId to copy, if available
unset($opt['versionId']);
}
// Handle metadata directive
$opt['headers']['x-amz-metadata-directive'] = 'COPY';
if ($source['bucket'] === $dest['bucket'] && $source['filename'] === $dest['filename'])
{
$opt['headers']['x-amz-metadata-directive'] = 'REPLACE';
}
if (isset($opt['metadataDirective']))
{
$opt['headers']['x-amz-metadata-directive'] = $opt['metadataDirective'];
unset($opt['metadataDirective']);
}
// Handle Access Control Lists. Can also pass canned ACLs as an HTTP header.
if (isset($opt['acl']) && is_array($opt['acl']))
{
$batch[] = $this->set_object_acl($dest['bucket'], $dest['filename'], $opt['acl'], array(
'returnCurlHandle' => true
));
unset($opt['acl']);
}
elseif (isset($opt['acl']))
{
$opt['headers']['x-amz-acl'] = $opt['acl'];
unset($opt['acl']);
}
// Handle storage settings. Can also be passed as an HTTP header.
if (isset($opt['storage']))
{
$opt['headers']['x-amz-storage-class'] = $opt['storage'];
unset($opt['storage']);
}
// Handle encryption settings. Can also be passed as an HTTP header.
if (isset($opt['encryption']))
{
$opt['headers']['x-amz-server-side-encryption'] = $opt['encryption'];
unset($opt['encryption']);
}
// Handle conditional-copy parameters
if (isset($opt['ifMatch']))
{
$opt['headers']['x-amz-copy-source-if-match'] = $opt['ifMatch'];
unset($opt['ifMatch']);
}
if (isset($opt['ifNoneMatch']))
{
$opt['headers']['x-amz-copy-source-if-none-match'] = $opt['ifNoneMatch'];
unset($opt['ifNoneMatch']);
}
if (isset($opt['ifUnmodifiedSince']))
{
$opt['headers']['x-amz-copy-source-if-unmodified-since'] = $opt['ifUnmodifiedSince'];
unset($opt['ifUnmodifiedSince']);
}
if (isset($opt['ifModifiedSince']))
{
$opt['headers']['x-amz-copy-source-if-modified-since'] = $opt['ifModifiedSince'];
unset($opt['ifModifiedSince']);
}
// Handle meta tags. Can also be passed as an HTTP header.
if (isset($opt['meta']))
{
foreach ($opt['meta'] as $meta_key => $meta_value)
{
// e.g., `My Meta Header` is converted to `x-amz-meta-my-meta-header`.
$opt['headers']['x-amz-meta-' . strtolower(str_replace(' ', '-', $meta_key))] = $meta_value;
}
unset($opt['meta']);
}
// Authenticate to S3
$response = $this->authenticate($dest['bucket'], $opt);
// Attempt to reset ACLs
$http = new CFRequest();
$http->send_multi_request($batch);
return $response;
}