📖

Author: codemasher

README.md

@@ -44,6 +44,7 @@ A transparent, framework-agnostic, easily extensible PHP [PSR-18](https://www.ph
 		- [RFC-7009: Token Revocation](https://datatracker.ietf.org/doc/html/rfc7009)
 		- [RFC-7636: PKCE](https://datatracker.ietf.org/doc/html/rfc7636) (Proof Key for Code Exchange)
 		- [RFC-9126: PAR](https://datatracker.ietf.org/doc/html/rfc9126) (Pushed Authorization Requests)
+        - ~~[RFC-9449: DPoP](https://datatracker.ietf.org/doc/html/rfc9449) (Demonstrating Proof of Possession)~~ ([planned](https://github.com/chillerlan/php-oauth/issues/3))
 	- Proprietary, OAuth-like authorization flows (e.g. [Last.fm](https://www.last.fm/api/authentication))
 	- Invalidation of access tokens (if supported by the provider)
 - Several built-in provider implementations ([see below](#implemented-providers))
@@ -67,6 +68,9 @@ A transparent, framework-agnostic, easily extensible PHP [PSR-18](https://www.ph
 - The user manual is at https://php-oauth.readthedocs.io/ ([sources](https://github.com/chillerlan/php-oauth/tree/main/docs))
 - An API documentation created with [phpDocumentor](https://www.phpdoc.org/) can be found at https://chillerlan.github.io/php-oauth/
 - The documentation for the `AccessToken`, `AuthenticatedUser` and `OAuthOptions` containers can be found here: [chillerlan/php-settings-container](https://github.com/chillerlan/php-settings-container#readme)
+- There is [the suite of get-token examples](https://php-oauth.readthedocs.io/en/main/Usage/Using-examples.html), which is mostly intended for development, and there are self-contained examples for a quickstart:
+	- [OAuth1 example](https://github.com/chillerlan/php-oauth/tree/main/examples/example-oauth1.php)
+	- [OAuth2 example](https://github.com/chillerlan/php-oauth/tree/main/examples/example-oauth2.php)
 
 
 ## Installation with [composer](https://getcomposer.org)
@@ -95,16 +99,6 @@ composer require chillerlan/php-oauth
 Note: replace `dev-main` with a [version constraint](https://getcomposer.org/doc/articles/versions.md#writing-version-constraints), e.g. `^1.0` - see [releases](https://github.com/chillerlan/php-oauth/releases) for valid versions.
 
 
-## Examples
-
-There is [the suite of get-token examples](https://php-oauth.readthedocs.io/en/main/Usage/Using-examples.html),
-which is mostly intended for development, and there are self-contained examples for a quickstart:
-
-- [OAuth1 example](https://github.com/chillerlan/php-oauth/tree/main/examples/example-oauth1.php)
-- [OAuth2 example](https://github.com/chillerlan/php-oauth/tree/main/examples/example-oauth2.php)
-
-
-
 # Implemented Providers
 
 <!-- TABLE-START -->

src/Storage/OAuthStorageInterface.php

@@ -15,10 +15,10 @@
 use Psr\Log\LoggerInterface;
 
 /**
- * Specifies the methods required for an OAuth token storage adapter
+ * Specifies the methods required for an OAuth storage adapter
  *
- * The token storage is intended to be invoked per-user,
- * for whom it can store tokens for any of the implemented providers.
+ * The storage is intended to be invoked per-user, for whom it can
+ * store tokens, state etc. for any of the implemented providers.
  *
  * The implementer must ensure that the same storage instance is not used for multiple users.
  */

tests/Attributes/Provider.php

@@ -15,6 +15,8 @@
 
 /**
  * Supplies the provider class name
+ *
+ * example: `#[Provider(GitHub::class)]`
  */
 #[Attribute(Attribute::TARGET_CLASS)]
 final class Provider{

tests/Core/AuthenticatedUserTest.php

@@ -16,7 +16,7 @@
 use PHPUnit\Framework\TestCase;
 
 /**
- *
+ * Tests the AuthenticatedUser class
  */
 final class AuthenticatedUserTest extends TestCase{
 
@@ -80,10 +80,10 @@ public static function displayNameProvider():array{
 	}
 
 	#[DataProvider('displayNameProvider')]
-	public function testSetDisplayName(string|null $displayName, string|null $expexted):void{
+	public function testSetDisplayName(string|null $displayName, string|null $expected):void{
 		$user = new AuthenticatedUser(['displayName' => $displayName]);
 
-		$this::assertSame($expexted, $user->displayName);
+		$this::assertSame($expected, $user->displayName);
 	}
 
 }

tests/Core/OAuthOptionsTest.php

@@ -16,7 +16,7 @@
 use PHPUnit\Framework\TestCase;
 
 /**
- *
+ * Tests the OAuthOptions class
  */
 class OAuthOptionsTest extends TestCase{
 

tests/Core/OAuthProviderFactoryTest.php

@@ -23,7 +23,7 @@
 use function realpath;
 
 /**
- *
+ * Tests the OAuthProviderFactory class
  */
 class OAuthProviderFactoryTest extends TestCase{
 	use HttpFactoryTrait;

tests/Core/UtilitiesTest.php

@@ -17,7 +17,7 @@
 use InvalidArgumentException, ReflectionClass;
 
 /**
- *
+ * Tests the Utilities class
  */
 class UtilitiesTest extends TestCase{
 

tests/Providers/Live/OAuth1ProviderLiveTestAbstract.php

@@ -12,6 +12,8 @@
 namespace chillerlan\OAuthTest\Providers\Live;
 
 /**
+ * OAuth1 live API test
+ *
  * @property \chillerlan\OAuth\Core\OAuth1Interface $provider
  */
 abstract class OAuth1ProviderLiveTestAbstract extends OAuthProviderLiveTestAbstract{

tests/Providers/Live/OAuth2ProviderLiveTestAbstract.php

@@ -17,6 +17,8 @@
 use function time;
 
 /**
+ * OAuth2 live API test
+ *
  * @property \chillerlan\OAuth\Core\OAuth2Interface $provider
  */
 abstract class OAuth2ProviderLiveTestAbstract extends OAuthProviderLiveTestAbstract{

tests/Providers/Live/OAuthProviderLiveTestAbstract.php

@@ -20,6 +20,8 @@
 use function constant, sprintf;
 
 /**
+ * abstract OAuth live API test
+ *
  * @property \chillerlan\OAuth\Core\OAuthInterface $provider
  */
 abstract class OAuthProviderLiveTestAbstract extends ProviderLiveTestAbstract{

tests/Providers/ProviderLiveTestAbstract.php

@@ -19,7 +19,7 @@
 use function defined;
 
 /**
- *
+ * The abstract base class for all live API tests
  */
 abstract class ProviderLiveTestAbstract extends ProviderUnitTestAbstract{
 
@@ -28,7 +28,9 @@ abstract class ProviderLiveTestAbstract extends ProviderUnitTestAbstract{
 	protected DotEnv $dotEnv;
 	protected string $ENV_PREFIX;
 
-	/** a test username for live API tests, defined in .env as {ENV-PREFIX}_TESTUSER*/
+	/**
+	 * a test username for live API tests, defined in `.env` as `<$provider::IDENTIFIER>_TESTUSER`
+	 */
 	protected string $TEST_USER = '';
 
 	/**

tests/Providers/ProviderLiveTestHttpClientFactory.php

@@ -23,7 +23,12 @@
 use function sprintf;
 
 /**
+ * A PSR-18 HTTP client factory for clients used in live API tests
  *
+ * The phpunit constant `HTTP_CLIENT_FACTORY` should be set with a valid FQCN for a `HttpClientFactoryInterface`
+ *
+ * @see  \chillerlan\PHPUnitHttp\HttpClientFactoryInterface
+ * @link https://github.com/chillerlan/phpunit-http
  */
 final class ProviderLiveTestHttpClientFactory implements HttpClientFactoryInterface{
 

tests/Providers/ProviderTestLoggerFactory.php

@@ -19,7 +19,7 @@
 use const JSON_UNESCAPED_SLASHES;
 
 /**
- *
+ * A simple PSR-3 logger factory used in provider tests
  */
 final class ProviderTestLoggerFactory{
 

tests/Providers/ProviderUnitTestAbstract.php

@@ -37,7 +37,7 @@
 use function sprintf;
 
 /**
- *
+ * The abstract base class for all provider tests
  */
 abstract class ProviderUnitTestAbstract extends TestCase{
 	use HttpFactoryTrait;
@@ -57,6 +57,9 @@ abstract class ProviderUnitTestAbstract extends TestCase{
 	protected const CFGDIR       = self::PROJECT_ROOT.'/.config';
 	protected const CACERT       = self::PROJECT_ROOT.'/tests/cacert.pem';
 
+	/**
+	 * Initializes the unit test
+	 */
 	protected function setUp():void{
 		ini_set('date.timezone', 'UTC');
 
@@ -93,6 +96,9 @@ protected function setUp():void{
 	 * init dependencies
 	 */
 
+	/**
+	 * Initializes the environment config (from `phpunit.xml`)
+	 */
 	protected function initConfig():void{
 
 		foreach(['TEST_ENVFILE'] as $constant){
@@ -103,6 +109,9 @@ protected function initConfig():void{
 
 	}
 
+	/**
+	 * Initializes an `OAuthOptions` instance
+	 */
 	protected function initOptions():OAuthOptions{
 		$options = new OAuthOptions;
 
@@ -114,6 +123,9 @@ protected function initOptions():OAuthOptions{
 		return $options;
 	}
 
+	/**
+	 * Initializes an `OAuthStorageInterface` instance
+	 */
 	protected function initStorage(OAuthOptions $options):OAuthStorageInterface{
 		return new MemoryStorage($options);
 	}
@@ -123,20 +135,29 @@ protected function initStorage(OAuthOptions $options):OAuthStorageInterface{
 	 * Reflection utilities
 	 */
 
+	/**
+	 * Sets a property in the current provider instance with the given value
+	 */
 	final protected function setReflectionProperty(string $property, mixed $value):void{
 		$this->reflection->getProperty($property)->setValue($this->provider, $value);
 	}
 
+	/**
+	 * Returns the current value of the given propertyin the current provider instance
+	 */
 	final protected function getReflectionProperty(string $property):mixed{
 		return $this->reflection->getProperty($property)->getValue($this->provider);
 	}
 
+	/**
+	 * Invokes a method vith the given arguments in the current provider instance
+	 */
 	final protected function invokeReflectionMethod(string $method, array $args = []):mixed{
 		return $this->reflection->getMethod($method)->invokeArgs($this->provider, $args);
 	}
 
 	/**
-	 * returns the fully qualified class name (FQCN) of the test subject
+	 * Returns the fully qualified class name (FQCN) of the test subject
 	 *
 	 * @see \chillerlan\OAuthTest\Attributes\Provider
 	 */
@@ -156,7 +177,7 @@ final protected function getProviderFQCN():string{
 	 */
 
 	/**
-	 * creates a stupid simple ClientInterface that returns the given response instance
+	 * Creates a stupid simple `ClientInterface` that returns the given response instance
 	 */
 	protected function getMockHttpClient(ResponseInterface $response):ClientInterface{
 		return new class ($response) implements ClientInterface{
@@ -174,7 +195,7 @@ public function sendRequest(RequestInterface $request):ResponseInterface{
 	}
 
 	/**
-	 * sets a custom response in the mock http client and sets the client in the current provider
+	 * Sets a custom response in the mock http client and sets the client in the current provider
 	 */
 	protected function setMockResponse(ResponseInterface|StreamInterface $response):void{
 

tests/Providers/ProviderUnitTestHttpClientFactory.php

@@ -17,7 +17,12 @@
 use Psr\Http\Message\ResponseFactoryInterface;
 
 /**
+ * A PSR-18 HTTP client factory for provider unit tests
  *
+ * This factory just returns an echo client, that returns the given request
+ *
+ * @see  \chillerlan\PHPUnitHttp\HttpClientFactoryInterface
+ * @link https://github.com/chillerlan/phpunit-http
  */
 final class ProviderUnitTestHttpClientFactory implements HttpClientFactoryInterface{
 

tests/Providers/Unit/OAuth1ProviderUnitTestAbstract.php

@@ -19,6 +19,8 @@
 use function str_starts_with;
 
 /**
+ * OAuth1 unit test
+ *
  * @property \chillerlan\OAuth\Core\OAuth1Interface $provider
  */
 abstract class OAuth1ProviderUnitTestAbstract extends OAuthProviderUnitTestAbstract{

tests/Providers/Unit/OAuth2ProviderUnitTestAbstract.php

@@ -25,6 +25,8 @@
 use function base64_encode, implode, json_decode, json_encode;
 
 /**
+ * OAuth2 unit test
+ *
  * @property \chillerlan\OAuth\Core\OAuth2Interface $provider
  */
 abstract class OAuth2ProviderUnitTestAbstract extends OAuthProviderUnitTestAbstract{

tests/Providers/Unit/OAuthProviderUnitTestAbstract.php

@@ -27,6 +27,8 @@
 use function sprintf;
 
 /**
+ * abstract OAuth unit test
+ *
  * @property \chillerlan\OAuth\Core\OAuthInterface $provider
  */
 abstract class OAuthProviderUnitTestAbstract extends ProviderUnitTestAbstract{

tests/Storage/FileStorageEncryptedTest.php

@@ -14,7 +14,7 @@
 use chillerlan\OAuth\OAuthOptions;
 
 /**
- * Tests the file storage (encrypted)
+ * Tests the `FileStorage` class (encrypted)
  */
 final class FileStorageEncryptedTest extends FileStorageTest{
 

tests/Storage/FileStorageTest.php

@@ -18,7 +18,7 @@
 use const DIRECTORY_SEPARATOR;
 
 /**
- * Tests the file storage
+ * Tests the `FileStorage` class
  */
 class FileStorageTest extends StorageTestAbstract{
 

tests/Storage/MemoryStorageTest.php

@@ -14,6 +14,9 @@
 use chillerlan\OAuth\OAuthOptions;
 use chillerlan\OAuth\Storage\{MemoryStorage, OAuthStorageInterface};
 
+/**
+ * Tests the `MemoryStorage` class
+ */
 final class MemoryStorageTest extends StorageTestAbstract{
 
 	protected function initStorage(OAuthOptions $options):OAuthStorageInterface{

tests/Storage/SessionStorageEncryptedTest.php

@@ -14,7 +14,7 @@
 use chillerlan\OAuth\OAuthOptions;
 
 /**
- * Tests the session storage (encrypted)
+ * Tests the `SessionStorage` class (encrypted)
  */
 final class SessionStorageEncryptedTest extends SessionStorageTest{
 

tests/Storage/SessionStorageTest.php

@@ -15,7 +15,7 @@
 use chillerlan\OAuth\Storage\{OAuthStorageInterface, SessionStorage};
 
 /**
- * Tests the session storage
+ * Tests the `SessionStorage` class
  */
 class SessionStorageTest extends StorageTestAbstract{
 

tests/Storage/StorageTestAbstract.php

@@ -20,6 +20,9 @@
 use ReflectionMethod;
 use function array_merge;
 
+/**
+ * The abstract storage test
+ */
 abstract class StorageTestAbstract extends TestCase{
 
 	protected const ENCRYPTION_KEY = '000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f';