Update discovery document and documentation for Requester Pays (googl…

…eapis#694)

* Update discovery document and documentation for Requester Pays

* Add requester pays to StorageClient methods

* Fix unit tests

* add coverage for requester pays on notifications

* Address code review, update documentation

* bump phpunit memory limit

* Add end to end unit test for notification user project

* Update userProject documentation

* Update argument documentation

phpunit.xml.dist

@@ -15,4 +15,7 @@
       </exclude>
     </whitelist>
   </filter>
+  <php>
+    <ini name="memory_limit" value="2048M"/>
+  </php>
 </phpunit>

src/Storage/Bucket.php

@@ -592,8 +592,7 @@ function (array $object) {
      */
     public function createNotification($topic, array $options = [])
     {
-        $res = $this->connection->insertNotification($options + [
-            'bucket' => $this->identity['bucket'],
+        $res = $this->connection->insertNotification($options + $this->identity + [
             'topic' => $this->getFormattedTopic($topic),
             'payload_format' => 'JSON_API_V1'
         ]);

src/Storage/Connection/Rest.php

@@ -265,7 +265,8 @@ public function insertObject(array $args = [])
             'bucket' => $args['bucket'],
             'query' => [
                 'predefinedAcl' => $args['predefinedAcl'],
-                'uploadType' => $uploadType
+                'uploadType' => $uploadType,
+                'userProject' => $args['userProject']
             ]
         ];
 
@@ -289,7 +290,8 @@ private function resolveUploadOptions(array $args)
             'resumable' => null,
             'streamable' => null,
             'predefinedAcl' => null,
-            'metadata' => []
+            'metadata' => [],
+            'userProject' => null,
         ];
 
         $args['data'] = Psr7\stream_for($args['data']);

src/Storage/Connection/ServiceDefinition/storage-v1.json

@@ -1,11 +1,11 @@
 {
   "kind": "discovery#restDescription",
-  "etag": "\"YWOzh2SDasdU84ArJnpYek-OMdg/aAU6-GJtzQTwC546w_DsCPIRIUA\"",
+  "etag": "\"YWOzh2SDasdU84ArJnpYek-OMdg/rE26AVrnFbD9orx-YtVO_pKNglE\"",
   "discoveryVersion": "v1",
   "id": "storage:v1",
   "name": "storage",
   "version": "v1",
-  "revision": "20170915",
+  "revision": "20170920",
   "title": "Cloud Storage JSON API",
   "description": "Stores and retrieves potentially large, immutable data objects.",
   "ownerDomain": "google.com",
@@ -3708,4 +3708,4 @@
       }
     }
   }
-}
+}

src/Storage/StorageClient.php

@@ -102,9 +102,9 @@ public function __construct(array $config = [])
      * point. To see the operations that can be performed on a bucket please
      * see {@see Google\Cloud\Storage\Bucket}.
      *
-     * If `$requesterPays` is set to true, the current project ID (used to
+     * If `$userProject` is set to true, the current project ID (used to
      * instantiate the client) will be billed for all requests. If
-     * `$requesterPays` is a project ID, given as a string, that project
+     * `$userProject` is a project ID, given as a string, that project
      * will be billed for all requests. This only has an effect when the bucket
      * is not owned by the current or given project ID.
      *
@@ -114,21 +114,22 @@ public function __construct(array $config = [])
      * ```
      *
      * @param string $name The name of the bucket to request.
-     * @param string|bool $requesterPays If true, the current Project ID
-     *        will be used. If a string, that string will be used as the userProject
-     *        argument. **Defaults to** `false`.
+     * @param string|bool $userProject If true, the current Project ID
+     *        will be used. If a string, that string will be used as the
+     *        userProject argument, and that project will be billed for the
+     *        request. **Defaults to** `false`.
      * @return Bucket
      */
-    public function bucket($name, $requesterPays = false)
+    public function bucket($name, $userProject = false)
     {
-        if (!$requesterPays) {
-            $requesterPays = null;
-        } elseif (!is_string($requesterPays)) {
-            $requesterPays = $this->projectId;
+        if (!$userProject) {
+            $userProject = null;
+        } elseif (!is_string($userProject)) {
+            $userProject = $this->projectId;
         }
 
         return new Bucket($this->connection, $name, [
-            'requesterProjectId' => $requesterPays
+            'requesterProjectId' => $userProject
         ]);
     }
 
@@ -167,20 +168,37 @@ public function bucket($name, $requesterPays = false)
      *           be either 'full' or 'noAcl'.
      *     @type string $fields Selector which will cause the response to only
      *           return the specified fields.
+     *     @type string $userProject If set, this is the ID of the project which
+     *           will be billed for the request.
+     *     @type bool $bucketUserProject If true, each returned instance will
+     *           have `$userProject` set to the value of `$options.userProject`.
+     *           If false, `$options.userProject` will be used ONLY for the
+     *           listBuckets operation. If `$options.userProject` is not set,
+     *           this option has no effect. **Defaults to** `true`.
      * }
      * @return ItemIterator<Google\Cloud\Storage\Bucket>
      */
     public function buckets(array $options = [])
     {
         $resultLimit = $this->pluck('resultLimit', $options, false);
 
+        $bucketUserProject = $this->pluck('bucketUserProject', $options, false);
+
+        $bucketUserProject = !is_null($bucketUserProject)
+            ? $bucketUserProject
+            : true;
+
+        $userProject = (isset($options['userProject']) && $bucketUserProject)
+            ? $options['userProject']
+            : null;
+
         return new ItemIterator(
             new PageIterator(
-                function (array $bucket) {
+                function (array $bucket) use ($userProject) {
                     return new Bucket(
                         $this->connection,
                         $bucket['name'],
-                        $bucket
+                        $bucket + ['requesterProjectId' => $userProject]
                     );
                 },
                 [$this->connection, 'listBuckets'],
@@ -258,16 +276,33 @@ function (array $bucket) {
      *     @type array $labels The Bucket labels. Labels are represented as an
      *           array of keys and values. To remove an existing label, set its
      *           value to `null`.
+     *     @type string $userProject If set, this is the ID of the project which
+     *           will be billed for the request.
+     *     @type bool $bucketUserProject If true, the returned instance will
+     *           have `$userProject` set to the value of `$options.userProject`.
+     *           If false, `$options.userProject` will be used ONLY for the
+     *           createBucket operation. If `$options.userProject` is not set,
+     *           this option has no effect. **Defaults to** `true`.
      * }
      * @return Bucket
      */
     public function createBucket($name, array $options = [])
     {
+        $bucketUserProject = $this->pluck('bucketUserProject', $options, false);
+
+        $bucketUserProject = !is_null($bucketUserProject)
+            ? $bucketUserProject
+            : true;
+
+        $userProject = (isset($options['userProject']) && $bucketUserProject)
+            ? $options['userProject']
+            : null;
+
         $response = $this->connection->insertBucket($options + ['name' => $name, 'project' => $this->projectId]);
         return new Bucket(
             $this->connection,
             $name,
-            $response
+            $response + ['requesterProjectId' => $userProject]
         );
     }
 

tests/unit/Storage/BucketTest.php

@@ -400,6 +400,7 @@ public function testCreatesNotification($topic, $expectedTopic)
     {
         $this->connection
             ->insertNotification([
+                'userProject' => null,
                 'bucket' => self::BUCKET_NAME,
                 'topic' => sprintf('//pubsub.googleapis.com/projects/%s/topics/%s', self::PROJECT_ID, $expectedTopic),
                 'payload_format' => 'JSON_API_V1'