docs: Add a sample outlining the usage of the Range header. (#2267)

* docs: Add a sample outlining usage of the Range header for subrange downloads * address review comments * docs: make a hyperlink Co-Authored-By: John Pedrie <[email protected]>
googleapis · Aug 26, 2019 · 654b974 · 654b974
1 parent 2709478
commit 654b974
Show file tree

Hide file tree

Showing 2 changed files with 60 additions and 0 deletions.
diff --git a/Storage/src/StorageObject.php b/Storage/src/StorageObject.php
@@ -549,12 +549,18 @@ public function rename($name, array $options = [])
     /**
      * Download an object as a string.
      *
+     * For an example of setting the range header to download a subrange of the
+     * object please see {@see Google\Cloud\Storage\StorageObject::downloadAsStream()}.
+     *
      * Example:
      * ```
      * $string = $object->downloadAsString();
      * echo $string;
      * ```
      *
+     * @see https://cloud.google.com/storage/docs/json_api/v1/objects/get Objects get API documentation.
+     * @see https://cloud.google.com/storage/docs/json_api/v1/parameters#range Learn more about the Range header.
+     *
      * @param array $options [optional] {
      *     Configuration Options.
      *
@@ -577,11 +583,17 @@ public function downloadAsString(array $options = [])
     /**
      * Download an object to a specified location.
      *
+     * For an example of setting the range header to download a subrange of the
+     * object please see {@see Google\Cloud\Storage\StorageObject::downloadAsStream()}.
+     *
      * Example:
      * ```
      * $stream = $object->downloadToFile(__DIR__ . '/my-file.txt');
      * ```
      *
+     * @see https://cloud.google.com/storage/docs/json_api/v1/objects/get Objects get API documentation.
+     * @see https://cloud.google.com/storage/docs/json_api/v1/parameters#range Learn more about the Range header.
+     *
      * @param string $path Path to download the file to.
      * @param array $options [optional] {
      *     Configuration Options.
@@ -614,12 +626,35 @@ public function downloadToFile($path, array $options = [])
     /**
      * Download an object as a stream.
      *
+     * Please note Google Cloud Storage respects the Range header as specified
+     * by [RFC7233](https://tools.ietf.org/html/rfc7233#section-3.1). See below
+     * for an example of this in action.
+     *
      * Example:
      * ```
      * $stream = $object->downloadAsStream();
      * echo $stream->getContents();
      * ```
      *
+     * ```
+     * // Set the Range header in order to download a subrange of the object. For more examples of
+     * // setting the Range header, please see [RFC7233](https://tools.ietf.org/html/rfc7233#section-3.1).
+     * $firstFiveBytes = '0-4'; // Get the first 5 bytes.
+     * $fromFifthByteToLastByte = '4-'; // Get the bytes starting with the 5th to the last.
+     * $lastFiveBytes = '-5'; // Get the last 5 bytes.
+     *
+     * $stream = $object->downloadAsStream([
+     *     'restOptions' => [
+     *         'headers' => [
+     *             'Range' => "bytes=$firstFiveBytes"
+     *         ]
+     *     ]
+     * ]);
+     * ```
+     *
+     * @see https://cloud.google.com/storage/docs/json_api/v1/objects/get Objects get API documentation.
+     * @see https://cloud.google.com/storage/docs/json_api/v1/parameters#range Learn more about the Range header.
+     *
      * @param array $options [optional] {
      *     Configuration Options.
      *
@@ -648,6 +683,9 @@ public function downloadAsStream(array $options = [])
     /**
      * Asynchronously download an object as a stream.
      *
+     * For an example of setting the range header to download a subrange of the
+     * object please see {@see Google\Cloud\Storage\StorageObject::downloadAsStream()}.
+     *
      * Example:
      * ```
      * use Psr\Http\Message\StreamInterface;
@@ -677,6 +715,8 @@ public function downloadAsStream(array $options = [])
      * Promise\unwrap($promises);
      * ```
      *
+     * @see https://cloud.google.com/storage/docs/json_api/v1/objects/get Objects get API documentation.
+     * @see https://cloud.google.com/storage/docs/json_api/v1/parameters#range Learn more about the Range header.
      * @see https://github.com/guzzle/promises Learn more about Guzzle Promises
      *
      * @param array $options [optional] {

diff --git a/Storage/tests/Snippet/StorageObjectTest.php b/Storage/tests/Snippet/StorageObjectTest.php
@@ -304,6 +304,26 @@ public function testDownloadAsStream()
         $this->assertEquals('test', $res->output());
     }
 
+    public function testDownloadAsStreamWithRangeHeaders()
+    {
+        $snippet = $this->snippetFromMethod(StorageObject::class, 'downloadAsStream', 1);
+        $snippet->addLocal('object', $this->object);
+        $this->connection->downloadObject([
+                'restOptions' => [
+                    'headers' => [
+                        'Range' => 'bytes=0-4'
+                    ]
+                ],
+                'bucket' => 'my-bucket',
+                'object' => 'my-object'
+            ])
+            ->shouldBeCalled()
+            ->willReturn(Psr7\stream_for('test'));
+        $this->object->___setProperty('connection', $this->connection->reveal());
+
+        $res = $snippet->invoke();
+    }
+
     public function testDownloadAsStreamAsync()
     {
         $snippet = $this->snippetFromMethod(StorageObject::class, 'downloadAsStreamAsync');