milesj/transit — pull request #15 by mfn (2014-11-13 16:50:09+00:00)
Title: Support any params to S3Client->putObject()

The current S3Client transport implementation only allows selected parameters to be passed to the `putObject()` method.

This PR add supports for a new key `params` which will be unioned with the existing putObject parameters and thus allows extending with arbitrary data.

##### Practical example
According to the [official documentation on putObject](http://docs.aws.amazon.com/aws-sdk-php/latest/class-Aws.S3.S3Client.html#_putObject), a multitude of different parameters are supported. E.g. if you want to set a custom `Cache-Control` HTTP header to be served with your S3 object, you pass the `CacheControl` parameter with the value. This patch allows this with:
```PHP
'Uploader.Attachment' => [
'upload_image' => [
# ...
'transport' => [
'class' => AttachmentBehavior::S3,
# ....
'params' => [
'CacheControl' => 'max-age=315360000',
],
],
],

```
The `Metadata` parameter is not sufficient because all it's keys get prefixed with `x-amz-meta-`.

In general, two further insights here:

1) This obsoletes the `meta` key, because the same could be achieved now with:
```PHP
'transport' => [
'class' => AttachmentBehavior::S3,
# ....
'params' => [
'Metadata' => [
'Foo' => 'Bar',
],
'CacheControl' => 'max-age=315360000',
],
],
```
But removal of `meta` would obviously cause a BC break and thus I didn't consider changing anything regarding to it.

2) The extra `params` are not considered for the larger files when using the `UploadBuilder`; rational: it currently doesn't support the same features either, as the `meta` for example is ignored for it already. This could *probably* achieved using the `setOption()`/`addOptions()` method of the builder, but I found this to be outside of the scope of this change.