Added downloadAsStream method to StorageObject

src/Storage/StorageObject.php

@@ -536,13 +536,7 @@ public function rename($name, array $options = [])
      */
     public function downloadAsString(array $options = [])
     {
-        return (string) $this->connection->downloadObject(
-            $this->formatEncryptionHeaders(
-                $options
-                + $this->encryptionData
-                + $this->identity
-            )
-        );
+        return (string) $this->downloadAsStream($options);
     }
 
     /**
@@ -573,13 +567,7 @@ public function downloadToFile($path, array $options = [])
         $destination = Psr7\stream_for(fopen($path, 'w'));
 
         Psr7\copy_to_stream(
-            $this->connection->downloadObject(
-                $this->formatEncryptionHeaders(
-                    $options
-                    + $this->encryptionData
-                    + $this->identity
-                )
-            ),
+            $this->downloadAsStream($options),
             $destination
         );
 
@@ -588,6 +576,40 @@ public function downloadToFile($path, array $options = [])
         return $destination;
     }
 
+    /**
+     * Download an object as a stream.
+     *
+     * Example:
+     * ```
+     * $stream = $object->downloadAsStream();
+     * echo $stream->getContents();
+     * ```
+     *
+     * @param array $options [optional] {
+     *     Configuration Options.
+     *
+     *     @type string $encryptionKey An AES-256 customer-supplied encryption
+     *           key. It will be neccesary to provide this when a key was used
+     *           during the object's creation. If provided one must also include
+     *           an `encryptionKeySHA256`.
+     *     @type string $encryptionKeySHA256 The SHA256 hash of the
+     *           customer-supplied encryption key. It will be neccesary to
+     *           provide this when a key was used during the object's creation.
+     *           If provided one must also include an `encryptionKey`.
+     * }
+     * @return StreamInterface
+     */
+    public function downloadAsStream(array $options = [])
+    {
+        return $this->connection->downloadObject(
+            $this->formatEncryptionHeaders(
+                $options
+                + $this->encryptionData
+                + $this->identity
+            )
+        );
+    }
+
     /**
      * Retrieves the object's details. If no object data is cached a network
      * request will be made to retrieve it.

tests/Storage/StorageObjectTest.php

@@ -23,12 +23,15 @@
 use Google\Cloud\Storage\StorageObject;
 use GuzzleHttp\Psr7;
 use Prophecy\Argument;
+use Prophecy\Prophecy\ObjectProphecy;
+use Psr\Http\Message\StreamInterface;
 
 /**
  * @group storage
  */
 class StorageObjectTest extends \PHPUnit_Framework_TestCase
 {
+    /** @var ConnectionInterface|ObjectProphecy */
     public $connection;
 
     public function setUp()
@@ -366,6 +369,58 @@ public function testDownloadsToFile()
         );
     }
 
+    public function testGetBodyWithoutExtraOptions()
+    {
+        $bucket = 'bucket';
+        $object = 'object.txt';
+        $stream = Psr7\stream_for($string = 'abcdefg');
+        $this->connection->downloadObject([
+            'bucket' => $bucket,
+            'object' => $object,
+            'generation' => null,
+        ])
+            ->willReturn($stream);
+
+        $object = new StorageObject($this->connection->reveal(), $object, $bucket);
+
+        $body = $object->downloadAsStream();
+
+        $this->assertInstanceOf(StreamInterface::class, $body);
+        $this->assertEquals($string, $body);
+    }
+
+    public function testGetBodyWithExtraOptions()
+    {
+        $key = 'abcd';
+        $hash = '1234';
+        $bucket = 'bucket';
+        $object = 'object.txt';
+        $stream = Psr7\stream_for($string = 'abcdefg');
+        $this->connection->downloadObject([
+            'bucket' => $bucket,
+            'object' => $object,
+            'generation' => null,
+            'httpOptions' => [
+                'headers' => [
+                    'x-goog-encryption-algorithm' => 'AES256',
+                    'x-goog-encryption-key' => base64_encode($key),
+                    'x-goog-encryption-key-sha256' => base64_encode($hash),
+                ]
+            ]
+        ])
+            ->willReturn($stream);
+
+        $object = new StorageObject($this->connection->reveal(), $object, $bucket);
+
+        $body = $object->downloadAsStream([
+            'encryptionKey' => $key,
+            'encryptionKeySHA256' => $hash
+        ]);
+
+        $this->assertInstanceOf(StreamInterface::class, $body);
+        $this->assertEquals($string, $body);
+    }
+
     public function testGetsInfo()
     {
         $objectInfo = [