feat: user-supplied query params for auth url (#2432)

Author: bshaffer

README.md

@@ -422,6 +422,28 @@ $client->setHttpClient($httpClient);
 
 Other Guzzle features such as [Handlers and Middleware](http://docs.guzzlephp.org/en/stable/handlers-and-middleware.html) offer even more control.
 
+### Partial Consent and Granted Scopes
+
+When using OAuth2 3LO (e.g. you're a client requesting credentials from a 3rd
+party, such as in the [simple file upload example](examples/simple-file-upload.php)),
+you may want to take advantage of Partial Consent.
+
+To allow clients to only grant certain scopes in the OAuth2 screen, pass the
+querystring parameter for `enable_serial_consent` when generating the
+authorization URL:
+
+```php
+$authUrl = $client->createAuthUrl($scope, ['enable_serial_consent' => 'true']);
+```
+
+Once the flow is completed, you can see which scopes were granted by calling
+`getGrantedScope` on the OAuth2 object:
+
+```php
+// Space-separated string of granted scopes if it exists, otherwise null.
+echo $client->getOAuth2Service()->getGrantedScope();
+```
+
 ### Service Specific Examples ###
 
 YouTube: https://github.com/youtube/api-samples/tree/master/php

src/Client.php

@@ -357,9 +357,10 @@ public function fetchAccessTokenWithRefreshToken($refreshToken = null)
      * The authorization endpoint allows the user to first
      * authenticate, and then grant/deny the access request.
      * @param string|array $scope The scope is expressed as an array or list of space-delimited strings.
+     * @param array $queryParams Querystring params to add to the authorization URL.
      * @return string
      */
-    public function createAuthUrl($scope = null)
+    public function createAuthUrl($scope = null, array $queryParams = [])
     {
         if (empty($scope)) {
             $scope = $this->prepareScopes();
@@ -390,7 +391,7 @@ public function createAuthUrl($scope = null)
             'response_type' => 'code',
             'scope' => $scope,
             'state' => $this->config['state'],
-        ]);
+        ]) + $queryParams;
 
         // If the list of scopes contains plus.login, add request_visible_actions
         // to auth URL.

tests/Google/ClientTest.php

@@ -1025,4 +1025,14 @@ public function testSetNewRedirectUri()
         $authUrl2 = $client->createAuthUrl();
         $this->assertStringContainsString(urlencode($redirectUri2), $authUrl2);
     }
+
+    public function testQueryParamsForAuthUrl()
+    {
+        $client = new Client();
+        $client->setRedirectUri('https://example.com');
+        $authUrl1 = $client->createAuthUrl(null, [
+            'enable_serial_consent' => 'true'
+        ]);
+        $this->assertStringContainsString('&enable_serial_consent=true', $authUrl1);
+    }
 }