diff --git a/README.md b/README.md index 97a6009..b166297 100644 --- a/README.md +++ b/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 diff --git a/src/Storage/OAuthStorageInterface.php b/src/Storage/OAuthStorageInterface.php index 2c23f01..32d4f88 100644 --- a/src/Storage/OAuthStorageInterface.php +++ b/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. */ diff --git a/tests/Attributes/Provider.php b/tests/Attributes/Provider.php index 6eb78be..cab4640 100644 --- a/tests/Attributes/Provider.php +++ b/tests/Attributes/Provider.php @@ -15,6 +15,8 @@ /** * Supplies the provider class name + * + * example: `#[Provider(GitHub::class)]` */ #[Attribute(Attribute::TARGET_CLASS)] final class Provider{ diff --git a/tests/Core/AuthenticatedUserTest.php b/tests/Core/AuthenticatedUserTest.php index 24f3fc9..e237e55 100644 --- a/tests/Core/AuthenticatedUserTest.php +++ b/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); } } diff --git a/tests/Core/OAuthOptionsTest.php b/tests/Core/OAuthOptionsTest.php index f2f7258..44b7673 100644 --- a/tests/Core/OAuthOptionsTest.php +++ b/tests/Core/OAuthOptionsTest.php @@ -16,7 +16,7 @@ use PHPUnit\Framework\TestCase; /** - * + * Tests the OAuthOptions class */ class OAuthOptionsTest extends TestCase{ diff --git a/tests/Core/OAuthProviderFactoryTest.php b/tests/Core/OAuthProviderFactoryTest.php index 0a052ee..c1cde6e 100644 --- a/tests/Core/OAuthProviderFactoryTest.php +++ b/tests/Core/OAuthProviderFactoryTest.php @@ -23,7 +23,7 @@ use function realpath; /** - * + * Tests the OAuthProviderFactory class */ class OAuthProviderFactoryTest extends TestCase{ use HttpFactoryTrait; diff --git a/tests/Core/UtilitiesTest.php b/tests/Core/UtilitiesTest.php index 2a743b6..446e143 100644 --- a/tests/Core/UtilitiesTest.php +++ b/tests/Core/UtilitiesTest.php @@ -17,7 +17,7 @@ use InvalidArgumentException, ReflectionClass; /** - * + * Tests the Utilities class */ class UtilitiesTest extends TestCase{ diff --git a/tests/Providers/Live/OAuth1ProviderLiveTestAbstract.php b/tests/Providers/Live/OAuth1ProviderLiveTestAbstract.php index 0bf69e3..de12540 100644 --- a/tests/Providers/Live/OAuth1ProviderLiveTestAbstract.php +++ b/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{ diff --git a/tests/Providers/Live/OAuth2ProviderLiveTestAbstract.php b/tests/Providers/Live/OAuth2ProviderLiveTestAbstract.php index ffd86ae..69c5ee9 100644 --- a/tests/Providers/Live/OAuth2ProviderLiveTestAbstract.php +++ b/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{ diff --git a/tests/Providers/Live/OAuthProviderLiveTestAbstract.php b/tests/Providers/Live/OAuthProviderLiveTestAbstract.php index 064d0da..b7abfb0 100644 --- a/tests/Providers/Live/OAuthProviderLiveTestAbstract.php +++ b/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{ diff --git a/tests/Providers/ProviderLiveTestAbstract.php b/tests/Providers/ProviderLiveTestAbstract.php index 1780e54..56c5ba7 100644 --- a/tests/Providers/ProviderLiveTestAbstract.php +++ b/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 = ''; /** diff --git a/tests/Providers/ProviderLiveTestHttpClientFactory.php b/tests/Providers/ProviderLiveTestHttpClientFactory.php index c79fc14..635f9b2 100644 --- a/tests/Providers/ProviderLiveTestHttpClientFactory.php +++ b/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{ diff --git a/tests/Providers/ProviderTestLoggerFactory.php b/tests/Providers/ProviderTestLoggerFactory.php index cf00502..8dec1af 100644 --- a/tests/Providers/ProviderTestLoggerFactory.php +++ b/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{ diff --git a/tests/Providers/ProviderUnitTestAbstract.php b/tests/Providers/ProviderUnitTestAbstract.php index bff7ef9..d478e22 100644 --- a/tests/Providers/ProviderUnitTestAbstract.php +++ b/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{ diff --git a/tests/Providers/ProviderUnitTestHttpClientFactory.php b/tests/Providers/ProviderUnitTestHttpClientFactory.php index 46d990b..0cb886e 100644 --- a/tests/Providers/ProviderUnitTestHttpClientFactory.php +++ b/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{ diff --git a/tests/Providers/Unit/OAuth1ProviderUnitTestAbstract.php b/tests/Providers/Unit/OAuth1ProviderUnitTestAbstract.php index e6dab27..71934ce 100644 --- a/tests/Providers/Unit/OAuth1ProviderUnitTestAbstract.php +++ b/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{ diff --git a/tests/Providers/Unit/OAuth2ProviderUnitTestAbstract.php b/tests/Providers/Unit/OAuth2ProviderUnitTestAbstract.php index 5788e1a..91bf591 100644 --- a/tests/Providers/Unit/OAuth2ProviderUnitTestAbstract.php +++ b/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{ diff --git a/tests/Providers/Unit/OAuthProviderUnitTestAbstract.php b/tests/Providers/Unit/OAuthProviderUnitTestAbstract.php index 87326a5..0fd3687 100644 --- a/tests/Providers/Unit/OAuthProviderUnitTestAbstract.php +++ b/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{ diff --git a/tests/Storage/FileStorageEncryptedTest.php b/tests/Storage/FileStorageEncryptedTest.php index d70ac88..cbe8b0d 100644 --- a/tests/Storage/FileStorageEncryptedTest.php +++ b/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{ diff --git a/tests/Storage/FileStorageTest.php b/tests/Storage/FileStorageTest.php index 605421c..a1d2c7a 100644 --- a/tests/Storage/FileStorageTest.php +++ b/tests/Storage/FileStorageTest.php @@ -18,7 +18,7 @@ use const DIRECTORY_SEPARATOR; /** - * Tests the file storage + * Tests the `FileStorage` class */ class FileStorageTest extends StorageTestAbstract{ diff --git a/tests/Storage/MemoryStorageTest.php b/tests/Storage/MemoryStorageTest.php index 280b4c0..4b8358e 100644 --- a/tests/Storage/MemoryStorageTest.php +++ b/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{ diff --git a/tests/Storage/SessionStorageEncryptedTest.php b/tests/Storage/SessionStorageEncryptedTest.php index 6f32e05..ce88368 100644 --- a/tests/Storage/SessionStorageEncryptedTest.php +++ b/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{ diff --git a/tests/Storage/SessionStorageTest.php b/tests/Storage/SessionStorageTest.php index 10ac282..88aff48 100644 --- a/tests/Storage/SessionStorageTest.php +++ b/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{ diff --git a/tests/Storage/StorageTestAbstract.php b/tests/Storage/StorageTestAbstract.php index 18cb514..20aebc3 100644 --- a/tests/Storage/StorageTestAbstract.php +++ b/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';