🚿 phpDoc cleanup

Author: codemasher

.phan/config.php

@@ -53,6 +53,5 @@
 	],
 	'suppress_issue_types'            => [
 		'PhanUndeclaredGlobalVariable', // happens in get-token examples
-		'PhanAccessMethodInternal', // interface methods tagged as @internal
 	],
 ];

.phpdoc/template/base.html.twig

@@ -7,6 +7,7 @@
 	],
 	"social": [
 		{ "iconClass": "fab fa-github", "url": "https://github.com/chillerlan/php-oauth"},
+		{ "iconClass": "fas fa-envelope-open-text", "url": "https://github.com/chillerlan/php-oauth/discussions"},
 	]
 }
 %}

src/Core/AccessToken.php

@@ -6,6 +6,8 @@
  * @author       Smiley <[email protected]>
  * @copyright    2017 Smiley
  * @license      MIT
+ *
+ * @filesource
  */
 declare(strict_types=1);
 
@@ -18,71 +20,66 @@
 /**
  * Access token implementation for any OAuth version.
  *
- * @see https://datatracker.ietf.org/doc/html/rfc5849#section-2.3
- * @see https://datatracker.ietf.org/doc/html/rfc6749#section-1.4
- *
- * // Oauth1
- * @property string|null                    $accessTokenSecret
- *
- * // Oauth2
- * @property array                          $scopes
- * @property string|null                    $refreshToken
- *
- * // common
- * @property string|null                    $accessToken
- * @property DateTime|DateInterval|int|null $expires
- * @property array                          $extraParams
- * @property string                         $provider
+ * @link https://datatracker.ietf.org/doc/html/rfc5849#section-2.3
+ * @link https://datatracker.ietf.org/doc/html/rfc6749#section-1.4
  */
 final class AccessToken extends SettingsContainerAbstract{
 
 	/**
 	 * Denotes an unknown end of lifetime, such a token should be considered as expired.
+	 *
+	 * @var int
 	 */
 	public const EXPIRY_UNKNOWN = -9001;
 
 	/**
 	 * Denotes a token which never expires
+	 *
+	 * @var int
 	 */
 	public const NEVER_EXPIRES = -9002;
 
 	/**
 	 * Defines a maximum expiry period (1 year)
+	 *
+	 * @var int
 	 */
 	public const EXPIRY_MAX = (86400 * 365);
 
 	/**
-	 * The access token secret (OAuth1)
+	 * (magic) The oauth access token
 	 */
-	protected string|null $accessTokenSecret = null;
+	protected string|null $accessToken = null;
 
 	/**
-	 * The oauth access token
+	 * (magic) The access token secret (OAuth1)
 	 */
-	protected string|null $accessToken = null;
+	protected string|null $accessTokenSecret = null;
 
 	/**
-	 * An optional refresh token (OAuth2)
+	 * (magic) An optional refresh token (OAuth2)
 	 */
 	protected string|null $refreshToken = null;
 
 	/**
-	 * The token expiration date/time
+	 * (magic) The token expiration time
+	 *
+	 * The getter accepts: `DateTime|DateInterval|int|null`
 	 */
 	protected int $expires = self::EXPIRY_UNKNOWN;
 
 	/**
-	 * Additional token parameters supplied by the provider
+	 * (magic) The scopes that are attached to this token
 	 */
-	protected array $extraParams = [];
+	protected array $scopes = [];
 
 	/**
-	 * The scopes that are attached to this token (OAuth2)
+	 * (magic) Additional token parameters supplied by the provider
 	 */
-	protected array $scopes = [];
+	protected array $extraParams = [];
 
 	/**
-	 * The provider who issued this token
+	 * (magic) The provider that issued the token
 	 */
 	protected string|null $provider = null;
 

src/Core/AuthenticatedUser.php

@@ -6,6 +6,8 @@
  * @author       smiley <[email protected]>
  * @copyright    2024 smiley
  * @license      MIT
+ *
+ * @filesource
  */
 declare(strict_types=1);
 
@@ -15,50 +17,44 @@
 use function intval, is_int, is_numeric, trim;
 
 /**
- * A simple read-only container for user data responses from `OAuthInterface::me()`
+ * A simple read-only container for user data responses
  *
- * @property string|null     $handle
- * @property string|null     $displayName
- * @property string|null     $email
- * @property string|int|null $id
- * @property string|null     $avatar
- * @property string|null     $url
- * @property array           $data
+ * @see \chillerlan\OAuth\Core\UserInfo::me()
  */
 final class AuthenticatedUser extends SettingsContainerAbstract{
 
 	/**
-	 * The user handle, account or tag name
+	 * (magic) The user handle, account or tag name
 	 */
 	protected string|null $handle = null;
 
 	/**
-	 * The user's display name
+	 * (magic) The user's display name
 	 */
 	protected string|null $displayName = null;
 
 	/**
-	 * The (main) email address
+	 * (magic) The (main) email address
 	 */
 	protected string|null $email = null;
 
 	/**
-	 * A user ID, may be string or integer
+	 * (magic) A user ID, may be string or integer
 	 */
 	protected string|int|null $id = null;
 
 	/**
-	 * An avatar URL
+	 * (magic) An avatar URL
 	 */
 	protected string|null $avatar = null;
 
 	/**
-	 * URL to the user profile
+	 * (magic) URL to the user profile
 	 */
 	protected string|null $url = null;
 
 	/**
-	 * The full user endpoint response
+	 * (magic) The full user endpoint response
 	 */
 	protected array $data = [];
 

src/Core/CSRFStateMismatchException.php

@@ -14,7 +14,9 @@
 use chillerlan\OAuth\OAuthException;
 
 /**
+ * Thrown on mismatching CSRF ("state") token
  *
+ * @see \chillerlan\OAuth\Core\CSRFToken
  */
 class CSRFStateMismatchException extends OAuthException{
 

src/Core/CSRFToken.php

@@ -14,8 +14,8 @@
 /**
  * Specifies the methods required for the OAuth2 CSRF token validation ("state parameter")
  *
- * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
- * @see https://datatracker.ietf.org/doc/html/rfc6749#section-10.12
+ * @link https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
+ * @link https://datatracker.ietf.org/doc/html/rfc6749#section-10.12
  */
 interface CSRFToken{
 
@@ -24,7 +24,6 @@ interface CSRFToken{
 	 * Throws a ProviderException if the given state is empty, unknown or doesn't match the known state.
 	 *
 	 * @throws \chillerlan\OAuth\Providers\ProviderException
-	 * @internal
 	 */
 	public function checkState(string|null $state = null):void;
 
@@ -33,7 +32,6 @@ public function checkState(string|null $state = null):void;
 	 * in the local storage for later verification. Returns the updated array of parameters.
 	 *
 	 * @throws \chillerlan\OAuth\Providers\ProviderException
-	 * @internal
 	 */
 	public function setState(array $params):array;
 

src/Core/ClientCredentials.php

@@ -14,12 +14,14 @@
 /**
  * Indicates whether the provider is capable of the OAuth2 client credentials authentication flow.
  *
- * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.4
+ * @link https://datatracker.ietf.org/doc/html/rfc6749#section-4.4
  */
 interface ClientCredentials{
 
 	/**
 	 * Obtains an OAuth2 client credentials token and returns an AccessToken
+	 *
+	 * @param string[]|null $scopes
 	 */
 	public function getClientCredentialsToken(array|null $scopes = null):AccessToken;
 

src/Core/InvalidAccessTokenException.php

@@ -12,7 +12,11 @@
 namespace chillerlan\OAuth\Core;
 
 /**
+ * Thrown when an access token is expired and cannot be refreshed
  *
+ * @see \chillerlan\OAuth\Core\TokenRefresh
+ * @see \chillerlan\OAuth\Core\OAuth1Provider::getRequestAuthorization()
+ * @see \chillerlan\OAuth\Core\OAuth2Provider::getRequestAuthorization()
  */
 class InvalidAccessTokenException extends UnauthorizedAccessException{
 

src/Core/OAuth1Interface.php

@@ -21,7 +21,7 @@ interface OAuth1Interface extends OAuthInterface{
 	 *
 	 * The $token (request token) supplied via `$_GET['oauth_token']` should be in the storage at this point.
 	 *
-	 * @see https://datatracker.ietf.org/doc/html/rfc5849#section-2.3
+	 * @link https://datatracker.ietf.org/doc/html/rfc5849#section-2.3
 	 */
 	public function getAccessToken(string $requestToken, string $verifier):AccessToken;