Create README

Author: BenjaminFavre

README.md

@@ -0,0 +1,75 @@
+# OAuth 2 decorator for the Symfony HTTP Client
+
+A decorator for the [Symfony HTTP Client](https://symfony.com/doc/current/http_client.html) that helps you call APIs endpoints protected with OAuth 2.
+It handles all the authentication protocol with the OAuth 2 server and let you focus solely on making your business API calls.
+
+Designed to be minimalist and lightweight, it has literally no dependency at all, apart the Symfony Contracts of course; and it requires only the PHP JSON extension.
+
+OAuth 2 is a relatively complex protocol which offers to authenticate in a wide variety of manners (called Grant Types in the OAuth jargon).
+This decorator aims to provide all standard Grant Types out of the box. Too often however, the OAuth 2 server you will have to authenticate to will not follow strict OAuth 2 standard.
+This is why the decorator has been designed such a way that every step of the authentication process is customizable.
+
+## Installation
+
+    composer require benjaminfavre/oauth2-http-client
+
+## Usage
+
+```php
+use Symfony\Component\HttpClient\HttpClient;
+use BenjaminFavre\OAuthHttpClient\OAuthHttpClient;
+use BenjaminFavre\OAuthHttpClient\GrantType\ClientCredentialsGrantType;
+
+$httpClient = HttpClient::create(); 
+
+// Here we will use the client credentials grant type but it could be any other grant type
+$grantType = new ClientCredentialsGrantType(
+    $httpClient,
+    'https://github.com/login/oauth/access_token', // The OAuth server token URL
+    'the-client-id',
+    'the-client-password'
+);
+
+$httpClient = new OAuthHttpClient($httpClient, $grantType);
+
+// Then use $httpClient to make your API calls:
+// $httpClient->request(...);
+```
+
+## How it works
+
+Each time you make an HTTP request, the decorator will:
+- Fetch an access token from cache or from the OAuth server if none is in cache;
+- Modify your request to add the access token (usually in a header);
+- Make the API call and return the response;
+- Optionally, try again with a new access token if the first API call failed because of token expiration.
+
+## Customization
+
+Implement any of the following interfaces in order to customize the relevant authentication step, and pass an instance of your class via the relevant Decorator setter.
+
+### GrantTypeInterface
+
+A class in charge of fetching an access token from the OAuth server.
+The decorator comes with four standard grant types:
+- AuthorizationCodeGrantType;
+- ClientCredentialsGrantType;
+- PasswordGrantType;
+- RefreshTokenGrantType.
+
+### TokensCacheInterface
+
+A class in charge of storing and fetching tokens from cache.
+By default, the decorator uses MemoryTokensCache that caches the tokens in memory.
+
+### RequestSignerInterface
+
+A class in charge of modifying the API request in order to add the access token.
+By default, the decorator uses BearerHeaderRequestSigner that adds the access token in the Authorization header.
+You can use the HeaderRequestSigner to add the access token in another header, or you can implement the interface for more customization.
+
+### ResponseCheckerInterface
+
+A class in charge of checking if the API call failed because of a token expiration.
+By default, the decorator uses StatusCode401ResponseChecker that identifies 401 response codes as the signal the access token needs to be renewed.
+It can lead to false positives (401 response code can be returned for other reasons than token expiration), so you can implement the interface if your OAuth server returns exploitable fine-grained error reasons.

composer.json

@@ -1,5 +1,16 @@
 {
-    "name": "benjaminfavre/oauth-http-client",
+    "name": "benjaminfavre/oauth2-http-client",
+    "description": "A lightweight OAuth 2 decorator for the Symfony HTTP Client.",
+    "keywords": ["symfony", "oauth", "http-client"],
+    "homepage": "https://github.com/BenjaminFavre/oauth2-http-client",
+    "license": "Apache-2.0",
+    "authors": [
+        {
+            "name": "Benjamin Favre",
+            "email": "[email protected]",
+            "homepage": "https://github.com/BenjaminFavre"
+        }
+    ],
     "autoload": {
         "psr-4": {"BenjaminFavre\\OAuthHttpClient\\": "src/"}
     },
@@ -9,6 +20,9 @@
         "symfony/http-client-contracts": "^2.3.1",
         "symfony/cache-contracts": "^2.2.0"
     },
+    "provide": {
+        "symfony/http-client-implementation": "^2.3.1"
+    },
     "require-dev": {
         "phpunit/phpunit": "^9.4.3",
         "symfony/cache": "5.2.0",

src/OAuthHttpClient.php

@@ -22,7 +22,7 @@ class OAuthHttpClient implements HttpClientInterface
     /** @var GrantTypeInterface */
     private $grant;
     /** @var RequestSignerInterface */
-    private $modifier;
+    private $signer;
     /** @var ResponseCheckerInterface */
     private $checker;
     /** @var TokensCacheInterface */
@@ -34,14 +34,14 @@ public function __construct(
     ) {
         $this->client = $client;
         $this->grant = $grant;
-        $this->modifier = new BearerHeaderRequestSigner();
+        $this->signer = new BearerHeaderRequestSigner();
         $this->checker = new StatusCode401ResponseChecker();
         $this->cache = new MemoryTokensCache();
     }
 
-    public function setModifier(RequestSignerInterface $modifier): self
+    public function setSigner(RequestSignerInterface $signer): self
     {
-        $this->modifier = $modifier;
+        $this->signer = $signer;
 
         return $this;
     }
@@ -69,7 +69,7 @@ public function request(string $method, string $url, array $options = []): Respo
 
         for ($tries = 0; $tries < 2; ++$tries) {
             $tokens = $this->cache->get($grant);
-            $this->modifier->modify($options, $tokens->getAccessToken());
+            $this->signer->modify($options, $tokens->getAccessToken());
             $response = $this->client->request($method, $url, $options);
 
             if (!$this->checker->hasAuthenticationFailed($response)) {

src/TokensCache/TokensCacheInterface.php

@@ -2,7 +2,7 @@
 
 namespace BenjaminFavre\OAuthHttpClient\TokensCache;
 
-use BenjaminFavre\OAuthHttpClient\GrantType\OAuthException;
+use BenjaminFavre\OAuthHttpClient\Exception\OAuthException;
 use BenjaminFavre\OAuthHttpClient\GrantType\GrantTypeInterface;
 use BenjaminFavre\OAuthHttpClient\GrantType\Tokens;