Merge pull request aws#629 from aws/feature/s3-saveas

Adding support for the SaveAs parameter to the S3 GetObject operation.

src/S3/S3Client.php

@@ -6,6 +6,7 @@
 use Aws\Api\Service;
 use Aws\AwsClient;
 use Aws\ClientResolver;
+use Aws\Command;
 use Aws\Exception\AwsException;
 use Aws\HandlerList;
 use Aws\Middleware;
@@ -75,6 +76,7 @@ public function __construct(array $args)
         $stack->appendSign(PutObjectUrlMiddleware::wrap(), 's3.put_object_url');
         $stack->appendSign(PermanentRedirectMiddleware::wrap(), 's3.permanent_redirect');
         $stack->appendInit(Middleware::sourceFile($this->getApi()), 's3.source_file');
+        $stack->appendInit($this->getSaveAsParameter(), 's3.save_as');
         $stack->appendInit($this->getLocationConstraintMiddleware(), 's3.location');
     }
 
@@ -429,7 +431,7 @@ private function checkExistenceWithCommand(CommandInterface $command)
     private function getLocationConstraintMiddleware()
     {
         return function (callable $handler) {
-            return function ($command, $request = null) use ($handler) {
+            return function (Command $command, $request = null) use ($handler) {
                 if ($command->getName() === 'CreateBucket') {
                     $region = $this->getRegion();
                     if ($region === 'us-east-1') {
@@ -444,6 +446,25 @@ private function getLocationConstraintMiddleware()
         };
     }
 
+    /**
+     * Provides a middleware that supports the `SaveAs` parameter.
+     *
+     * @return \Closure
+     */
+    private function getSaveAsParameter()
+    {
+        return function (callable $handler) {
+            return function (Command $command, $request = null) use ($handler) {
+                if ($command->getName() === 'GetObject' && isset($command['SaveAs'])) {
+                    $command['@http']['sink'] = $command['SaveAs'];
+                    unset($command['SaveAs']);
+                }
+
+                return $handler($command, $request);
+            };
+        };
+    }
+
     /** @internal */
     public static function _applyRetryConfig($value, $_, HandlerList $list)
     {
@@ -491,19 +512,23 @@ public static function applyDocFilters(array $api, array $docs)
         $api['shapes']['PutObjectRequest']['members']['SourceFile'] = ['shape' => 'SourceFile'];
         $api['shapes']['UploadPartRequest']['members']['SourceFile'] = ['shape' => 'SourceFile'];
 
+        // Add the SaveAs parameter.
+        $docs['shapes']['SaveAs']['base'] = 'The path to a file on disk to save the object data.';
+        $api['shapes']['SaveAs'] = ['type' => 'string'];
+        $api['shapes']['GetObjectRequest']['members']['SaveAs'] = ['shape' => 'SaveAs'];
+
         // Several SSECustomerKey documentation updates.
         $docs['shapes']['SSECustomerKey']['append'] = $b64;
         $docs['shapes']['CopySourceSSECustomerKey']['append'] = $b64;
         $docs['shapes']['SSECustomerKeyMd5']['append'] = '<div class="alert alert-info">The value will be computed on '
             . 'your behalf if it is not supplied.</div>';
 
         // Add the ObjectURL to various output shapes and documentation.
-        $objectUrl = 'The URI of the created object.';
+        $docs['shapes']['ObjectURL']['base'] = 'The URI of the created object.';
         $api['shapes']['ObjectURL'] = ['type' => 'string'];
         $api['shapes']['PutObjectOutput']['members']['ObjectURL'] = ['shape' => 'ObjectURL'];
         $api['shapes']['CopyObjectOutput']['members']['ObjectURL'] = ['shape' => 'ObjectURL'];
         $api['shapes']['CompleteMultipartUploadOutput']['members']['ObjectURL'] = ['shape' => 'ObjectURL'];
-        $docs['shapes']['ObjectURL']['base'] = $objectUrl;
 
         // Fix references to Location Constraint.
         unset($api['shapes']['CreateBucketRequest']['payload']);

tests/S3/S3ClientTest.php

@@ -1,7 +1,6 @@
 <?php
 namespace Aws\Test\S3;
 
-use Aws\MockHandler;
 use Aws\Result;
 use Aws\S3\S3Client;
 use Aws\Test\UsesServiceTrait;
@@ -332,4 +331,24 @@ public function getTestCasesForLocationConstraints()
             ['us-west-2', 'HeadBucket',   false],
         ];
     }
+
+    public function testSaveAsParamAddsSink()
+    {
+        $client = $this->getTestClient('S3', [
+            'http_handler' => function ($request, array $options) {
+                $this->assertArrayHasKey('sink', $options);
+                return Promise\promise_for(
+                    new Psr7\Response(200, [], 'sink=' . $options['sink'])
+                );
+            }
+        ]);
+
+        $result = $client->getObject([
+            'Bucket' => 'foo',
+            'Key'    => 'bar',
+            'SaveAs' => 'baz',
+        ]);
+
+        $this->assertEquals('sink=baz', (string) $result['Body']);
+    }
 }