📖

chillerlan · Mar 8, 2024 · 99d3a79 · 99d3a79
1 parent ea68331
commit 99d3a79
Show file tree

Hide file tree

Showing 40 changed files with 110 additions and 44 deletions.
diff --git a/src/Providers/Amazon.php b/src/Providers/Amazon.php
@@ -16,12 +16,10 @@
 use function sprintf;
 
 /**
- * Amazon Login/OAuth
+ * Login with Amazon for Websites (OAuth2)
  *
- * @see https://login.amazon.com/
- * @see https://developer.amazon.com/docs/login-with-amazon/documentation-overview.html
- * @see https://images-na.ssl-images-amazon.com/images/G/01/lwa/dev/docs/website-developer-guide._TTH_.pdf
- * @see https://images-na.ssl-images-amazon.com/images/G/01/mwsportal/doc/en_US/offamazonpayments/LoginAndPayWithAmazonIntegrationGuide._V335378063_.pdf
+ * @see https://developer.amazon.com/docs/login-with-amazon/web-docs.html
+ * @see https://developer.amazon.com/docs/login-with-amazon/conceptual-overview.html
  */
 class Amazon extends OAuth2Provider implements CSRFToken, TokenRefresh{
 
@@ -37,7 +35,6 @@ class Amazon extends OAuth2Provider implements CSRFToken, TokenRefresh{
 	protected string      $authURL        = 'https://www.amazon.com/ap/oa';
 	protected string      $accessTokenURL = 'https://www.amazon.com/ap/oatoken';
 	protected string      $apiURL         = 'https://api.amazon.com';
-	protected string|null $apiDocs        = 'https://login.amazon.com/';
 	protected string|null $applicationURL = 'https://sellercentral.amazon.com/hz/home';
 
 	/**

diff --git a/src/Providers/AzureActiveDirectory.php b/src/Providers/AzureActiveDirectory.php
@@ -13,7 +13,11 @@
 use chillerlan\OAuth\Core\{CSRFToken, OAuth2Provider};
 
 /**
- * @see https://docs.microsoft.com/azure/active-directory/develop/v2-app-types
+ * Microsoft identity platform (OAuth2)
+ *
+ * @see https://learn.microsoft.com/en-us/entra/identity-platform/v2-app-types
+ * @see https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow
+ * @see https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow
  */
 abstract class AzureActiveDirectory extends OAuth2Provider implements CSRFToken{
 

diff --git a/src/Providers/BattleNet.php b/src/Providers/BattleNet.php
@@ -17,9 +17,9 @@
 use function in_array, sprintf, strtolower;
 
 /**
- * Battle.net OAuth
+ * Battle.net OAuth2
  *
- * @see https://develop.battle.net/documentation
+ * @see https://develop.battle.net/documentation/guides/using-oauth
  */
 class BattleNet extends OAuth2Provider implements ClientCredentials, CSRFToken{
 

diff --git a/src/Providers/BigCartel.php b/src/Providers/BigCartel.php
@@ -17,7 +17,7 @@
 use const SODIUM_BASE64_VARIANT_ORIGINAL;
 
 /**
- * BigCartel OAuth
+ * BigCartel OAuth2
  *
  * @see https://developers.bigcartel.com/api/v1
  * @see https://bigcartel.wufoo.com/confirm/big-cartel-api-application/
@@ -30,7 +30,7 @@ class BigCartel extends OAuth2Provider implements CSRFToken, TokenInvalidate{
 
 	protected string      $authURL        = 'https://my.bigcartel.com/oauth/authorize';
 	protected string      $accessTokenURL = 'https://api.bigcartel.com/oauth/token';
-	protected string      $revokeURL      = 'https://api.bigcartel.com/oauth/deauthorize/%s'; // sprintf() user id!
+	protected string      $revokeURL      = 'https://api.bigcartel.com/oauth/deauthorize';
 	protected string      $apiURL         = 'https://api.bigcartel.com/v1';
 	protected string|null $userRevokeURL  = 'https://my.bigcartel.com/account';
 	protected string|null $apiDocs        = 'https://developers.bigcartel.com/api/v1';
@@ -70,7 +70,7 @@ public function invalidateAccessToken(AccessToken|null $token = null):bool{
 		$auth = sodium_bin2base64(sprintf('%s:%s', $this->options->key, $this->options->secret), SODIUM_BASE64_VARIANT_ORIGINAL);
 
 		$request = $this->requestFactory
-			->createRequest('POST', sprintf($this->revokeURL, $this->getAccountID($token)))
+			->createRequest('POST', sprintf('%s/%s', $this->revokeURL, $this->getAccountID($token)))
 			->withHeader('Authorization', sprintf('Basic %s', $auth))
 		;
 

diff --git a/src/Providers/Bitbucket.php b/src/Providers/Bitbucket.php
@@ -16,6 +16,8 @@
 use function sprintf;
 
 /**
+ * Bitbucket OAuth2 (Atlassian)
+ *
  * @see https://developer.atlassian.com/cloud/bitbucket/oauth-2/
  */
 class Bitbucket extends OAuth2Provider implements ClientCredentials, CSRFToken, TokenRefresh{

diff --git a/src/Providers/Deezer.php b/src/Providers/Deezer.php
@@ -17,6 +17,8 @@
 use const PHP_QUERY_RFC1738;
 
 /**
+ * Deezer OAuth2
+ *
  * @see https://developers.deezer.com/api/oauth
  *
  * sure, you *can* use different parameter names than the standard ones... and what about JSON?

diff --git a/src/Providers/DeviantArt.php b/src/Providers/DeviantArt.php
@@ -17,6 +17,8 @@
 use function sprintf;
 
 /**
+ * DeviantArt OAuth2
+ *
  * @see https://www.deviantart.com/developers/
  */
 class DeviantArt extends OAuth2Provider implements ClientCredentials, CSRFToken, TokenInvalidate, TokenRefresh{

diff --git a/src/Providers/Discogs.php b/src/Providers/Discogs.php
@@ -16,6 +16,8 @@
 use function sprintf;
 
 /**
+ * Discogs OAuth1
+ *
  * @see https://www.discogs.com/developers/
  * @see https://www.discogs.com/developers/#page:authentication,header:authentication-oauth-flow
  */

diff --git a/src/Providers/Discord.php b/src/Providers/Discord.php
@@ -16,6 +16,8 @@
 use function sprintf;
 
 /**
+ * Discord OAuth2
+ *
  * @see https://discord.com/developers/docs/topics/oauth2
  */
 class Discord extends OAuth2Provider implements ClientCredentials, CSRFToken, TokenRefresh, TokenInvalidate{
@@ -54,7 +56,7 @@ class Discord extends OAuth2Provider implements ClientCredentials, CSRFToken, To
 	protected string      $accessTokenURL = 'https://discordapp.com/api/oauth2/token';
 	protected string      $revokeURL      = 'https://discordapp.com/api/oauth2/token/revoke';
 	protected string      $apiURL         = 'https://discordapp.com/api';
-	protected string|null $apiDocs        = 'https://discordapp.com/developers/';
+	protected string|null $apiDocs        = 'https://discord.com/developers/';
 	protected string|null $applicationURL = 'https://discordapp.com/developers/applications/';
 
 	/**

diff --git a/src/Providers/Flickr.php b/src/Providers/Flickr.php
@@ -16,6 +16,8 @@
 use function array_merge, sprintf;
 
 /**
+ * Flickr OAuth1
+ *
  * @see https://www.flickr.com/services/api/auth.oauth.html
  * @see https://www.flickr.com/services/api/
  */

diff --git a/src/Providers/Foursquare.php b/src/Providers/Foursquare.php
@@ -16,8 +16,9 @@
 use function array_merge, explode, sprintf;
 
 /**
- * @see https://developer.foursquare.com/docs/
- * @see https://developer.foursquare.com/overview/auth
+ * Foursquare OAuth2
+ *
+ * @see https://location.foursquare.com/developer/reference/personalization-apis-authentication
  */
 class Foursquare extends OAuth2Provider{
 
@@ -30,7 +31,7 @@ class Foursquare extends OAuth2Provider{
 	protected string      $accessTokenURL  = 'https://foursquare.com/oauth2/access_token';
 	protected string      $apiURL          = 'https://api.foursquare.com';
 	protected string|null $userRevokeURL   = 'https://foursquare.com/settings/connections';
-	protected string|null $apiDocs         = 'https://developer.foursquare.com/docs';
+	protected string|null $apiDocs         = 'https://location.foursquare.com/developer/reference/foursquare-apis-overview';
 	protected string|null $applicationURL  = 'https://foursquare.com/developers/apps';
 
 	/**

diff --git a/src/Providers/GitHub.php b/src/Providers/GitHub.php
@@ -16,9 +16,11 @@
 use function sprintf;
 
 /**
- * @see https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/
- * @see https://developer.github.com/v3/
- * @see https://docs.github.com/en/developers/apps/building-github-apps/refreshing-user-to-server-access-tokens
+ * GitHub OAuth2
+ *
+ * @see https://docs.github.com/en/apps/oauth-apps/building-oauth-apps
+ * @see https://docs.github.com/rest
+ * @see https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens
  */
 class GitHub extends OAuth2Provider implements CSRFToken, TokenRefresh{
 
@@ -66,7 +68,7 @@ class GitHub extends OAuth2Provider implements CSRFToken, TokenRefresh{
 	protected string      $accessTokenURL = 'https://github.com/login/oauth/access_token';
 	protected string      $apiURL         = 'https://api.github.com';
 	protected string|null $userRevokeURL  = 'https://github.com/settings/applications';
-	protected string|null $apiDocs        = 'https://developer.github.com/';
+	protected string|null $apiDocs        = 'https://docs.github.com/rest';
 	protected string|null $applicationURL = 'https://github.com/settings/developers';
 
 	/**

diff --git a/src/Providers/GitLab.php b/src/Providers/GitLab.php
@@ -16,14 +16,15 @@
 use function sprintf;
 
 /**
+ * GitLab OAuth2
+ *
  * @see https://docs.gitlab.com/ee/api/oauth2.html
  */
 class GitLab extends OAuth2Provider implements ClientCredentials, CSRFToken, TokenRefresh{
 
 	protected string      $authURL        = 'https://gitlab.com/oauth/authorize';
 	protected string      $accessTokenURL = 'https://gitlab.com/oauth/token';
 	protected string      $apiURL         = 'https://gitlab.com/api';
-	protected string|null $apiDocs        = 'https://docs.gitlab.com/ee/api/README.html';
 	protected string|null $applicationURL = 'https://gitlab.com/profile/applications';
 
 	/**

diff --git a/src/Providers/Google.php b/src/Providers/Google.php
@@ -16,8 +16,10 @@
 use function sprintf;
 
 /**
- * @see https://developers.google.com/identity/protocols/OAuth2WebServer
- * @see https://developers.google.com/identity/protocols/OAuth2ServiceAccount
+ * Google OAuth2
+ *
+ * @see https://developers.google.com/identity/protocols/oauth2/web-server
+ * @see https://developers.google.com/identity/protocols/oauth2/service-account
  * @see https://developers.google.com/oauthplayground/
  */
 class Google extends OAuth2Provider implements CSRFToken{

diff --git a/src/Providers/GuildWars2.php b/src/Providers/GuildWars2.php
@@ -16,7 +16,9 @@
 use function implode, preg_match, sprintf, str_starts_with, substr;
 
 /**
- * GW2 does not support authentication (anymore) but the API still works like a regular OAUth API, so...
+ * Guild Wars 2
+ *
+ * Note: GW2 does not support authentication (anymore) but the API still works like a regular OAUth API, so...
  *
  * @see https://api.guildwars2.com/v2
  * @see https://wiki.guildwars2.com/wiki/API:Main
@@ -34,8 +36,6 @@ class GuildWars2 extends OAuth2Provider{
 	public const SCOPE_PROGRESSION = 'progression';
 	public const SCOPE_GUILDS      = 'guilds';
 
-	protected const AUTH_ERRMSG = 'GuildWars2 does not support authentication anymore.';
-
 	protected string      $authURL        = 'https://api.guildwars2.com/v2/tokeninfo';
 	protected string      $apiURL         = 'https://api.guildwars2.com';
 	protected string|null $userRevokeURL  = 'https://account.arena.net/applications';
@@ -62,8 +62,7 @@ public function storeGW2Token(string $access_token):AccessToken{
 		$tokeninfo = MessageUtil::decodeJSON($this->http->sendRequest($request));
 
 		if(isset($tokeninfo->id) && str_starts_with($access_token, $tokeninfo->id)){
-			$token = $this->createAccessToken();
-
+			$token                    = $this->createAccessToken();
 			$token->accessToken       = $access_token;
 			$token->accessTokenSecret = substr($access_token, 36, 36); // the actual token
 			$token->expires           = AccessToken::EOL_NEVER_EXPIRES;
@@ -87,15 +86,15 @@ public function storeGW2Token(string $access_token):AccessToken{
 	 * @throws \chillerlan\OAuth\Providers\ProviderException
 	 */
 	public function getAuthURL(array|null $params = null, array|null $scopes = null):UriInterface{
-		throw new ProviderException($this::AUTH_ERRMSG);
+		throw new ProviderException('GuildWars2 does not support authentication anymore.');
 	}
 
 	/**
 	 * @inheritdoc
 	 * @throws \chillerlan\OAuth\Providers\ProviderException
 	 */
 	public function getAccessToken(string $code, string|null $state = null):AccessToken{
-		throw new ProviderException($this::AUTH_ERRMSG);
+		throw new ProviderException('GuildWars2 does not support authentication anymore.');
 	}
 
 	/**

diff --git a/src/Providers/Imgur.php b/src/Providers/Imgur.php
@@ -16,6 +16,8 @@
 use function sprintf;
 
 /**
+ * Imgur OAuth2
+ *
  * Note: imgur sends an "expires_in" of 315360000 (10 years!) for access tokens,
  *       but states in the docs that tokens expire after one month.
  *       Either manually saving the expiry with the token to trigger auto refresh

diff --git a/src/Providers/LastFM.php b/src/Providers/LastFM.php
@@ -18,6 +18,8 @@
 use const PHP_QUERY_RFC1738;
 
 /**
+ * Last.fm
+ *
  * @see https://www.last.fm/api/authentication
  */
 class LastFM extends OAuthProvider{

diff --git a/src/Providers/MailChimp.php b/src/Providers/MailChimp.php
@@ -17,8 +17,10 @@
 use function array_merge, sprintf;
 
 /**
- * @see http://developer.mailchimp.com/
- * @see http://developer.mailchimp.com/documentation/mailchimp/guides/how-to-use-oauth2/
+ * MailChimp OAuth2
+ *
+ * @see https://mailchimp.com/developer/
+ * @see https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/
  */
 class MailChimp extends OAuth2Provider implements CSRFToken{
 
@@ -27,7 +29,7 @@ class MailChimp extends OAuth2Provider implements CSRFToken{
 
 	protected string      $authURL        = 'https://login.mailchimp.com/oauth2/authorize';
 	protected string      $accessTokenURL = 'https://login.mailchimp.com/oauth2/token';
-	protected string|null $apiDocs        = 'https://developer.mailchimp.com/';
+	protected string|null $apiDocs        = 'https://mailchimp.com/developer/';
 	protected string|null $applicationURL = 'https://admin.mailchimp.com/account/oauth2/';
 
 	/**

diff --git a/src/Providers/Mastodon.php b/src/Providers/Mastodon.php
@@ -18,6 +18,8 @@
 use const PHP_QUERY_RFC1738;
 
 /**
+ * Mastodon OAuth2 (v4.x instances)
+ *
  * @see https://docs.joinmastodon.org/client/intro/
  * @see https://docs.joinmastodon.org/methods/apps/oauth/
  */

diff --git a/src/Providers/MicrosoftGraph.php b/src/Providers/MicrosoftGraph.php
@@ -15,7 +15,9 @@
 use function sprintf;
 
 /**
- * @see https://docs.microsoft.com/graph/permissions-reference
+ * Microsoft Graph OAuth2
+ *
+ * @see https://learn.microsoft.com/en-us/graph/permissions-reference
  */
 class MicrosoftGraph extends AzureActiveDirectory{
 
@@ -32,7 +34,7 @@ class MicrosoftGraph extends AzureActiveDirectory{
 	];
 
 	protected string      $apiURL  = 'https://graph.microsoft.com';
-	protected string|null $apiDocs = 'https://docs.microsoft.com/graph/overview';
+	protected string|null $apiDocs = 'https://learn.microsoft.com/graph/overview';
 
 	/**
 	 * @inheritDoc

diff --git a/src/Providers/Mixcloud.php b/src/Providers/Mixcloud.php
@@ -16,7 +16,9 @@
 use function sprintf;
 
 /**
- * note: a missing slash at the end of the path will end up in an HTTP/301
+ * Mixcloud OAuth2
+ *
+ * note: a missing slash at the end of the path will end up in a HTTP/301
  *
  * @see https://www.mixcloud.com/developers/
  */

diff --git a/src/Providers/MusicBrainz.php b/src/Providers/MusicBrainz.php
@@ -17,6 +17,8 @@
 use const PHP_QUERY_RFC1738;
 
 /**
+ * MusicBrainz OAuth2
+ *
  * @see https://musicbrainz.org/doc/Development
  * @see https://musicbrainz.org/doc/Development/OAuth2
  */

diff --git a/src/Providers/NPROne.php b/src/Providers/NPROne.php
@@ -16,6 +16,8 @@
 use function in_array, ltrim, rtrim, sprintf, strtolower, str_contains;
 
 /**
+ * NPR API services (OAuth2)
+ *
  * @see https://dev.npr.org
  * @see https://github.com/npr/npr-one-backend-proxy-php
  */

diff --git a/src/Providers/OpenCaching.php b/src/Providers/OpenCaching.php
@@ -16,6 +16,8 @@
 use function implode, sprintf;
 
 /**
+ * Opencaching OAuth1
+ *
  * @see https://www.opencaching.de/okapi/
  */
 class OpenCaching extends OAuth1Provider{

diff --git a/src/Providers/OpenStreetmap.php b/src/Providers/OpenStreetmap.php
@@ -16,6 +16,8 @@
 use function sprintf, strip_tags;
 
 /**
+ * OpenStreetmap OAuth1 (deprecated)
+ *
  * @see https://wiki.openstreetmap.org/wiki/API
  * @see https://wiki.openstreetmap.org/wiki/OAuth
  *

diff --git a/src/Providers/OpenStreetmap2.php b/src/Providers/OpenStreetmap2.php
@@ -16,11 +16,11 @@
 use function sprintf, strip_tags;
 
 /**
+ * OpenStreetmap OAuth2
+ *
  * @see https://wiki.openstreetmap.org/wiki/API
  * @see https://wiki.openstreetmap.org/wiki/OAuth
  * @see https://www.openstreetmap.org/.well-known/oauth-authorization-server
- *
- * @see https://github.com/chillerlan/php-oauth-providers/issues/2
  */
 class OpenStreetmap2 extends OAuth2Provider implements CSRFToken{