Merge branch 'feature/3-upstream-league-clients' into develop

Fixes #3 Conflicts: CHANGELOG.md
phly · Nov 12, 2019 · cb84c34 · cb84c34
2 parents 5e33653 + bc5f4d1
commit cb84c34
Show file tree

Hide file tree

Showing 14 changed files with 220 additions and 178 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,27 +2,33 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
-## 1.1.0 - TBD
+## 2.0.0 - 2019-11-12
 
 ### Added
 
-- Nothing.
+- [#3](https://github.com/phly/phly-expressive-oauth2clientauthentication/pull/3) adds support for all League OAuth2 Clients that inherits from the upstream `League\OAuth2\Client\Provider\AbstractProvider`.
+
+- [#3](https://github.com/phly/phly-expressive-oauth2clientauthentication/pull/3) adds the method `forProviderKey(string $provider)` in `MissingProviderConfigException` in order to assert that the provider key has been set for providers in the configuration.
 
 ### Changed
 
-- Nothing.
+- [#3](https://github.com/phly/phly-expressive-oauth2clientauthentication/pull/3) changes array disposition in the configuration files to include `provider` and `options` keys **(BC break)**. The provider array key tells the factory what to instantiate, and the options value is passed to the `Provider` constructor.  Read the documentation on [local/environment-specific configuration](https://phly.github.io/phly-expressive-oauth2clientauthentication/config/) for specific implementation details and examples.
+
+- [#3](https://github.com/phly/phly-expressive-oauth2clientauthentication/pull/3) allows the username to default to `$resourceOwner->getId()` in method `getUsernameFromResourceOwner(ResourceOwnerInterface $resourceOwner) : string` if methods `$resourceOwner->getEmail()` and `$resourceOwner->getNickname()` don't exist, instead of throwing an `UnexpectedResourceOwnerTypeException`.
 
 ### Deprecated
 
 - Nothing.
 
 ### Removed
 
-- Nothing.
+- [#3](https://github.com/phly/phly-expressive-oauth2clientauthentication/pull/3) removes `UnsupportedProviderException`, as it is not used anymore.
+
+- [#3](https://github.com/phly/phly-expressive-oauth2clientauthentication/pull/3) removes `UnexpectedResourceOwnerTypeException`, as it is not used anymore.
 
 ### Fixed
 
-- Nothing.
+- [#3](https://github.com/phly/phly-expressive-oauth2clientauthentication/pull/3) fixes a namespace reference within a shipped config file.
 
 ## 1.0.1 - TBD
 

diff --git a/README.md b/README.md
@@ -5,14 +5,6 @@
 
 This library provides a [league/oauth2-client](http://oauth2-client.thephpleague.com)
 adapter for use with [zend-expressive-authentication](https://docs.zendframework.com/zend-expressive-authentication).
-It currently supports only the OAuth2 providers officially maintained by that
-project, including:
-
-- Facebook
-- GitHub
-- Google
-- Instagram
-- LinkedIn
 
 ## Installation
 

diff --git a/config/oauth2clientauthentication.global.php b/config/oauth2clientauthentication.global.php
@@ -5,7 +5,7 @@
  * @copyright Copyright (c) Matthew Weier O'Phinney
  */
 
-namespace Phly\OAuth2ClientAuthentication;
+namespace Phly\Expressive\OAuth2ClientAuthentication;
 
 return [
     'oauth2clientauthentication' => [

diff --git a/config/oauth2clientauthentication.local.php b/config/oauth2clientauthentication.local.php
@@ -5,7 +5,7 @@
  * @copyright Copyright (c) Matthew Weier O'Phinney
  */
 
-namespace Phly\OAuth2ClientAuthentication;
+namespace Phly\Expressive\OAuth2ClientAuthentication;
 
 return [
     'oauth2clientauthentication' => [
@@ -14,60 +14,88 @@
         // Each OAuth2 provider has its own configuration. You may need to review
         // http://oauth2-client.thephpleague.com/providers/league/ for details
         // on each and what configuration options they accept.
-        //
-        // We do not currently support any third-party providers; if you wish to
-        // do so, you will need to extend the `OAuth2ProviderFactory` to enable
-        // them.
 
         // Debug
         // This is the debug provider shipped within this component for purposes
         // of testing the OAuth2 client workflow within your applications.
         'debug' => [
-            // Provide this if you have provided an alternate route path via
-            // the oauth2clientauthentication.routes.debug key:
-            // 'callback_uri_template' => '/alternate/debug/callback?code=%s&state=%s',
+            // Provider key must be present for factory creation.
+            'provider' => Debug\DebugProvider::class,
+            'options' => [
+                // Provide this if you have provided an alternate route path via
+                // the oauth2clientauthentication.routes.debug key:
+                // 'callback_uri_template' => '/alternate/debug/callback?code=%s&state=%s',
 
-            // Provide this if you want to use an alternate path for the OAuth2
-            // "server" authorization:
-            // 'authorization_url' => '/alternate/debug/authorization',
+                // Provide this if you want to use an alternate path for the OAuth2
+                // "server" authorization:
+                // 'authorization_url' => '/alternate/debug/authorization',
+            ]
         ],
 
         // Facebook
         // 'facebook' => [
-        //     'clientId' => '{facebook-app-id}',
-        //     'clientSecret' => '{facebook-app-secret}',
-        //     'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
-        //     'graphApiVersion' => 'v2.10',
+        //     'provider' => Provider\Facebook::class,
+        //     'options' => [
+        //         'clientId' => '{facebook-app-id}',
+        //         'clientSecret' => '{facebook-app-secret}',
+        //         'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //         'graphApiVersion' => 'v2.10',
+        //     ],
         // ],
 
         // GitHub
         // 'github' => [
-        //     'clientId' => '{github-client-id}',
-        //     'clientSecret' => '{github-client-secret}',
-        //     'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //     'provider' => Provider\Github::class,
+        //     'options' => [
+        //         'clientId' => '{github-client-id}',
+        //         'clientSecret' => '{github-client-secret}',
+        //         'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //     ],
         // ],
 
         // Google
         // 'google' => [
-        //     'clientId' => '{google-client-id}',
-        //     'clientSecret' => '{google-client-secret}',
-        //     'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
-        //     'hostedDomain' => '', // scheme + domain of your app
+        //     'provider' => Provider\Google::class,
+        //     'options' => [
+        //         'clientId' => '{google-client-id}',
+        //         'clientSecret' => '{google-client-secret}',
+        //         'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //         'hostedDomain' => '', // scheme + domain of your app
+        //     ],
         // ],
 
         // Instagram
         // 'instagram' => [
-        //     'clientId' => '{instagram-client-id}',
-        //     'clientSecret' => '{instagram-client-secret}',
-        //     'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
-        //     'host' => 'https://api.instagram.com', // Optional; this is the default
+        //     'provider' => Provider\Instagram::class,
+        //     'options' => [
+        //        'clientId' => '{instagram-client-id}',
+        //        'clientSecret' => '{instagram-client-secret}',
+        //        'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //        'host' => 'https://api.instagram.com', // Optional; this is the default
+        //     ],
         // ],
 
         // LinkedIn
         // 'linkedin' => [
-        //     'clientId' => '{linkedin-client-id}',
-        //     'clientSecret' => '{linkedin-client-secret}',
-        //     'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //     'provider' => Provider\LinkedIn::class,
+        //     'options' => [
+        //         'clientId' => '{linkedin-client-id}',
+        //         'clientSecret' => '{linkedin-client-secret}',
+        //         'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //     ],
+        // ],
+
+        // Customized
+        // 'custom' => [
+        //    'provider' => Provider\GenericProvider::class,
+        //    'options' => [
+        //        'clientId' => '',
+        //        'clientSecret' => '',
+        //        'redirectUri' => '',
+        //        'urlAuthorize' => '',
+        //        'urlAccessToken' => '',
+        //        'urlResourceOwnerDetails' => '',
+        //    ],
         // ],
     ],
     'dependencies' => [

diff --git a/docs/book/config.md b/docs/book/config.md
@@ -23,13 +23,15 @@ return [
 
         // Configure the production and debug routes for OAuth2 client callbacks
         // if desired. These strings will be relative to the 'auth_path' config
-        // as specified above.
+        // as specified above. Provider names in the regex should match the keys 
+        // associated with enabled providers in configuration. The "custom" string 
+        // is just an example of a provider key named "custom" described below.
         'routes' => [
             // Production path.
-            // 'production' => '/{provider:facebook|github|google|instagram}|linkedin[/oauth2callback]',
+            // 'production' => '/{provider:facebook|github|google|instagram|linkedin|custom}[/oauth2callback]',
 
             // Debug path.
-            // 'debug' => '/{provider:debug|facebook|github|google|instagram|linkedin}[/oauth2callback]',
+            // 'debug' => '/{provider:debug|facebook|github|google|instagram|linkedin|custom}[/oauth2callback]',
         ],
     ],
 ];
@@ -42,6 +44,9 @@ review the [league/oauth2-client providers documentation](http://oauth2-client.t
 for links to both full configuration documentation, as well as resources on how
 to obtain the various client identifiers and secrets you will need to use.
 
+Each provider you define needs at least the provider key with the client class name and 
+the options key with an array which is passed to the client constructor.
+
 This information should _not_ be shipped directly in your repository, but rather
 included as part of your application environment.
 
@@ -50,55 +55,87 @@ included as part of your application environment.
 
 return [
     'oauth2clientauthentication' => [
-        // Debug
-        // This is the debug provider shipped within this component for purposes
-        // of testing the OAuth2 client workflow within your applications.
         'debug' => [
-            // Provide this if you have provided an alternate route path via
-            // the oauth2clientauthentication.routes.debug key:
-            // 'callback_uri_template' => '/alternate/debug/callback?code=%s&state=%s',
-
-            // Provide this if you want to use an alternate path for the OAuth2
-            // "server" authorization:
-            // 'authorization_url' => '/alternate/debug/authorization',
+            // Provider key must be present for factory creation.
+            'provider' => Debug\DebugProvider::class,
+            'options' => [
+                // Provide this if you have provided an alternate route path via
+                // the oauth2clientauthentication.routes.debug key:
+                // 'callback_uri_template' => '/alternate/debug/callback?code=%s&state=%s',
+
+                // Provide this if you want to use an alternate path for the OAuth2
+                // "server" authorization:
+                // 'authorization_url' => '/alternate/debug/authorization',
+            ]
         ],
 
         // Facebook
         // 'facebook' => [
-        //     'clientId' => '{facebook-app-id}',
-        //     'clientSecret' => '{facebook-app-secret}',
-        //     'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
-        //     'graphApiVersion' => 'v2.10',
+        //     'provider' => Provider\Facebook::class,
+        //     'options' => [
+        //         'clientId' => '{facebook-app-id}',
+        //         'clientSecret' => '{facebook-app-secret}',
+        //         'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //         'graphApiVersion' => 'v2.10',
+        //     ],
         // ],
 
         // GitHub
         // 'github' => [
-        //     'clientId' => '{github-client-id}',
-        //     'clientSecret' => '{github-client-secret}',
-        //     'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //     'provider' => Provider\Github::class,
+        //     'options' => [
+        //         'clientId' => '{github-client-id}',
+        //         'clientSecret' => '{github-client-secret}',
+        //         'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //     ],
         // ],
 
         // Google
         // 'google' => [
-        //     'clientId' => '{google-client-id}',
-        //     'clientSecret' => '{google-client-secret}',
-        //     'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
-        //     'hostedDomain' => '', // scheme + domain of your app
+        //     'provider' => Provider\Google::class,
+        //     'options' => [
+        //         'clientId' => '{google-client-id}',
+        //         'clientSecret' => '{google-client-secret}',
+        //         'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //         'hostedDomain' => '', // scheme + domain of your app
+        //     ],
         // ],
 
         // Instagram
         // 'instagram' => [
-        //     'clientId' => '{instagram-client-id}',
-        //     'clientSecret' => '{instagram-client-secret}',
-        //     'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
-        //     'host' => 'https://api.instagram.com', // Optional; this is the default
+        //     'provider' => Provider\Instagram::class,
+        //     'options' => [
+        //        'clientId' => '{instagram-client-id}',
+        //        'clientSecret' => '{instagram-client-secret}',
+        //        'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //        'host' => 'https://api.instagram.com', // Optional; this is the default
+        //     ],
         // ],
 
         // LinkedIn
         // 'linkedin' => [
-        //     'clientId' => '{linkedin-client-id}',
-        //     'clientSecret' => '{linkedin-client-secret}',
-        //     'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //     'provider' => Provider\LinkedIn::class,
+        //     'options' => [
+        //         'clientId' => '{linkedin-client-id}',
+        //         'clientSecret' => '{linkedin-client-secret}',
+        //         'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
+        //     ],
+        // ],
+
+        // Customized
+        // It's possible to configure any provider that extend the League AbstractProvider, including custom 
+        // implementations or extensions. This example uses GenericProvider which can be used with any OAuth 
+        // 2.0 Server that uses Bearer tokens.
+        // 'custom' => [
+        //    'provider' => Provider\GenericProvider::class,
+        //    'options' => [
+        //        'clientId' => '',
+        //        'clientSecret' => '',
+        //        'redirectUri' => '',
+        //        'urlAuthorize' => '',
+        //        'urlAccessToken' => '',
+        //        'urlResourceOwnerDetails' => '',
+        //    ],
         // ],
     ],
     'dependencies' => [

diff --git a/docs/book/debug.md b/docs/book/debug.md
@@ -13,21 +13,24 @@ when that occurs, the debug provider is added to the list of allowed providers,
 and its authorization handler is mapped to a route.
 
 You can configure both the authorization URI as well as the template for the
-callback URI:
+callback URI in the options array:
 
 ```php
 // e.g. config/autoload/oauth2-client.local.php:
 
 return [
     'oauth2clientauthentication' => [
         'debug' => [
-            // Provide this if you have provided an alternate route path via
-            // the oauth2clientauthentication.routes.debug key:
-            // 'callback_uri_template' => '/alternate/debug/callback?code=%s&state=%s',
+            'provider' => Debug\DebugProvider::class,
+            'options' => [
+                // Provide this if you have provided an alternate route path via
+                // the oauth2clientauthentication.routes.debug key:
+                // 'callback_uri_template' => '/alternate/debug/callback?code=%s&state=%s',
 
-            // Provide this if you want to use an alternate path for the OAuth2
-            // "server" authorization:
-            // 'authorization_url' => '/alternate/debug/authorization',
+                // Provide this if you want to use an alternate path for the OAuth2
+                // "server" authorization:
+                // 'authorization_url' => '/alternate/debug/authorization',
+            ]
         ],
     ],
 ];

diff --git a/docs/book/intro.md b/docs/book/intro.md
@@ -2,14 +2,7 @@
 
 This library provides a [league/oauth2-client](http://oauth2-client.thephpleague.com)
 adapter for use with [zend-expressive-authentication](https://docs.zendframework.com/zend-expressive-authentication).
-It currently supports only the OAuth2 providers officially maintained by that
-project, including:
-
-- Facebook
-- GitHub
-- Google
-- Instagram
-- LinkedIn
+It supports all OAuth2 Clients that inherit from `League\OAuth2\Client\Provider\AbstractProvider`.
 
 ## Installation
 

diff --git a/src/Exception/MissingProviderConfigException.php b/src/Exception/MissingProviderConfigException.php
@@ -20,4 +20,14 @@ public static function forProvider(string $provider) : self
             $provider
         ));
     }
+
+    public static function forProviderKey(string $provider) : self
+    {
+        return new self(sprintf(
+            'No provider key found for OAuth2 provider "%s"; please provide it via '
+            . 'the config key oauth2clientauthentication.%s.provider',
+            $provider,
+            $provider
+        ));
+    }
 }