Implement stream wrapper for gs://

README.md

@@ -154,6 +154,21 @@ $object = $bucket->object('file_backup.txt');
 $object->downloadToFile('/data/file_backup.txt');
 ```
 
+#### Stream Wrapper
+
+```php
+require 'vendor/autoload.php';
+
+use Google\Cloud\Storage\StorageClient;
+
+$storage = new StorageClient([
+    'projectId' => 'my_project'
+]);
+$storage->registerAsStreamWrapper();
+
+$contents = file_get_contents('gs://my_bucket/file_backup.txt');
+```
+
 ## Google Cloud Translation (Alpha)
 
 - [API Documentation](http://googlecloudplatform.github.io/google-cloud-php/#/docs/latest/translate/translateclient)

src/Storage/Bucket.php

@@ -310,6 +310,74 @@ public function getResumableUploader($data, array $options = [])
         );
     }
 
+    /**
+     * Get a streamable uploader which can provide greater control over the
+     * upload process. This is useful for generating large files and uploading
+     * the contents in chunks.
+     *
+     * Example:
+     * ```
+     * $uploader = $bucket->getStreamableUploader(
+     *     "initial contents",
+     *     ['name' => 'data.txt']
+     * );
+     *
+     * $uploader->write('some line');
+     * $uploader->write('more data');
+     * // finish uploading the item
+     * $uploader->upload();
+     * ```
+     *
+     * @see https://cloud.google.com/storage/docs/json_api/v1/how-tos/upload#resumable Learn more about resumable
+     * uploads.
+     * @see https://cloud.google.com/storage/docs/json_api/v1/objects/insert Objects insert API documentation.
+     *
+     * @param string|resource|StreamInterface $data The data to be uploaded.
+     * @param array $options [optional] {
+     *     Configuration options.
+     *
+     *     @type string $name The name of the destination.
+     *     @type bool $validate Indicates whether or not validation will be
+     *           applied using md5 hashing functionality. If true and the
+     *           calculated hash does not match that of the upstream server the
+     *           upload will be rejected.
+     *     @type int $chunkSize If provided the upload will be done in chunks.
+     *           The size must be in multiples of 262144 bytes. With chunking
+     *           you have increased reliability at the risk of higher overhead.
+     *           It is recommended to not use chunking.
+     *     @type string $predefinedAcl Predefined ACL to apply to the object.
+     *           Acceptable values include `"authenticatedRead`",
+     *           `"bucketOwnerFullControl`", `"bucketOwnerRead`", `"private`",
+     *           `"projectPrivate`", and `"publicRead"`.
+     *     @type array $metadata The available options for metadata are outlined
+     *           at the [JSON API docs](https://cloud.google.com/storage/docs/json_api/v1/objects/insert#request-body).
+     *     @type string $encryptionKey A base64 encoded AES-256 customer-supplied
+     *           encryption key.
+     *     @type string $encryptionKeySHA256 Base64 encoded SHA256 hash of the
+     *           customer-supplied encryption key. This value will be calculated
+     *           from the `encryptionKey` on your behalf if not provided, but
+     *           for best performance it is recommended to pass in a cached
+     *           version of the already calculated SHA.
+     * }
+     * @return StreamableUploader
+     * @throws \InvalidArgumentException
+     */
+    public function getStreamableUploader($data, array $options = [])
+    {
+        if (is_string($data) && !isset($options['name'])) {
+            throw new \InvalidArgumentException('A name is required when data is of type string.');
+        }
+
+        return $this->connection->insertObject(
+            $this->formatEncryptionHeaders($options) + [
+                'bucket' => $this->identity['bucket'],
+                'data' => $data,
+                'streamable' => true,
+                'validate' => false
+            ]
+        );
+    }
+
     /**
      * Lazily instantiates an object. There are no network requests made at this
      * point. To see the operations that can be performed on an object please

src/Storage/Connection/Rest.php

@@ -24,6 +24,7 @@
 use Google\Cloud\Upload\AbstractUploader;
 use Google\Cloud\Upload\MultipartUploader;
 use Google\Cloud\Upload\ResumableUploader;
+use Google\Cloud\Upload\StreamableUploader;
 use Google\Cloud\UriTrait;
 use GuzzleHttp\Psr7;
 use GuzzleHttp\Psr7\Request;
@@ -230,10 +231,16 @@ public function downloadObject(array $args = [])
     public function insertObject(array $args = [])
     {
         $args = $this->resolveUploadOptions($args);
-        $isResumable = $args['resumable'];
-        $uploadType = $isResumable
-            ? AbstractUploader::UPLOAD_TYPE_RESUMABLE
-            : AbstractUploader::UPLOAD_TYPE_MULTIPART;
+
+        $uploadType = AbstractUploader::UPLOAD_TYPE_RESUMABLE;
+        if ($args['streamable']) {
+            $uploaderClass = StreamableUploader::class;
+        } elseif ($args['resumable']) {
+            $uploaderClass = ResumableUploader::class;
+        } else {
+            $uploaderClass = MultipartUploader::class;
+            $uploadType = AbstractUploader::UPLOAD_TYPE_MULTIPART;
+        }
 
         $uriParams = [
             'bucket' => $args['bucket'],
@@ -243,16 +250,7 @@ public function insertObject(array $args = [])
             ]
         ];
 
-        if ($isResumable) {
-            return new ResumableUploader(
-                $this->requestWrapper,
-                $args['data'],
-                $this->expandUri(self::UPLOAD_URI, $uriParams),
-                $args['uploaderOptions']
-            );
-        }
-
-        return new MultipartUploader(
+        return new $uploaderClass(
             $this->requestWrapper,
             $args['data'],
             $this->expandUri(self::UPLOAD_URI, $uriParams),
@@ -270,6 +268,7 @@ private function resolveUploadOptions(array $args)
             'name' => null,
             'validate' => true,
             'resumable' => null,
+            'streamable' => null,
             'predefinedAcl' => null,
             'metadata' => []
         ];

src/Storage/StorageClient.php

@@ -217,4 +217,32 @@ public function createBucket($name, array $options = [])
         $response = $this->connection->insertBucket($options + ['name' => $name, 'project' => $this->projectId]);
         return new Bucket($this->connection, $name, $response);
     }
+
+    /**
+     * Registers this StorageClient as the handler for stream reading/writing.
+     *
+     * @param string $protocol The name of the protocol to use. Defaults to
+     *        'gs'.
+     * @throws \RuntimeException
+     */
+    public function registerAsStreamWrapper(string $protocol = null)
+    {
+        if (StreamWrapper::register($protocol)) {
+            StreamWrapper::setClient($this);
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Unregisters the SteamWrapper
+     *
+     * @param string $protocol The name of the protocol to unregister. Defaults
+     *        to 'gs'.
+     */
+    public function unregisterAsStreamWrapper(string $protocol = null)
+    {
+        StreamWrapper::unregister($protocol);
+        StreamWrapper::setClient(null);
+    }
 }