Skip to content
This repository was archived by the owner on Mar 23, 2024. It is now read-only.

Commit c24bbb1

Browse files
codemashercodemasher
committed
:octocat: +interface docblocks
1 parent 367fc5f commit c24bbb1

13 files changed

+118
-126
lines changed

‎src/Core/AccessToken.php‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,6 @@ public function __construct(iterable $properties = null){
9191
}
9292

9393
/**
94-
* AccessToken setter
95-
*
9694
* @param int|null $expires
9795
*
9896
* @return void

‎src/Core/ClientCredentials.php‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,14 @@
1515
interface ClientCredentials{
1616

1717
/**
18+
* Obtains an OAuth2 client credentials token and returns an AccessToken
19+
*
20+
* @link https://tools.ietf.org/html/rfc6749#section-4.4
21+
*
1822
* @param array $scopes
1923
*
2024
* @return \chillerlan\OAuth\Core\AccessToken
25+
* @throws \chillerlan\OAuth\Core\ProviderException
2126
*/
2227
public function getClientCredentialsToken(array $scopes = null):AccessToken;
2328

‎src/Core/OAuth1Interface.php‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,25 @@
1515
interface OAuth1Interface extends OAuthInterface{
1616

1717
/**
18+
* Obtains an OAuth1 request token and returns an AccessToken
19+
* object for use in the authentication request
20+
*
21+
* @see \chillerlan\OAuth\Core\OAuth1Provider::getAuthURL()
22+
*
1823
* @return \chillerlan\OAuth\Core\AccessToken
24+
* @throws \chillerlan\OAuth\Core\ProviderException
1925
*/
2026
public function getRequestToken():AccessToken;
2127

2228
/**
29+
* Obtains an OAuth1 access token with the given $token and $verifier
30+
* and returns an AccessToken object
31+
*
2332
* @param string $token
2433
* @param string $verifier
2534
*
2635
* @return \chillerlan\OAuth\Core\AccessToken
36+
* @throws \chillerlan\OAuth\Core\ProviderException
2737
*/
2838
public function getAccessToken(string $token, string $verifier):AccessToken;
2939

‎src/Core/OAuth1Provider.php‎

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,7 @@ abstract class OAuth1Provider extends OAuthProvider implements OAuth1Interface{
2929
protected $requestTokenURL;
3030

3131
/**
32-
* @param array $params
33-
*
34-
* @return \Psr\Http\Message\UriInterface
32+
* @inheritDoc
3533
*/
3634
public function getAuthURL(array $params = null):UriInterface{
3735

@@ -44,7 +42,7 @@ public function getAuthURL(array $params = null):UriInterface{
4442
}
4543

4644
/**
47-
* @return \chillerlan\OAuth\Core\AccessToken
45+
* @inheritDoc
4846
*/
4947
public function getRequestToken():AccessToken{
5048

@@ -161,10 +159,7 @@ protected function getSignature(string $url, array $params, string $method, stri
161159
}
162160

163161
/**
164-
* @param string $token
165-
* @param string $verifier
166-
*
167-
* @return \chillerlan\OAuth\Core\AccessToken
162+
* @inheritDoc
168163
*/
169164
public function getAccessToken(string $token, string $verifier):AccessToken{
170165
$request = $this->requestFactory
@@ -178,10 +173,7 @@ public function getAccessToken(string $token, string $verifier):AccessToken{
178173
}
179174

180175
/**
181-
* @param \Psr\Http\Message\RequestInterface $request
182-
* @param \chillerlan\OAuth\Core\AccessToken $token
183-
*
184-
* @return \Psr\Http\Message\RequestInterface
176+
* @inheritDoc
185177
*/
186178
public function getRequestAuthorization(RequestInterface $request, AccessToken $token):RequestInterface{
187179
$uri = $request->getUri();

‎src/Core/OAuth2Interface.php‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,14 +38,21 @@ interface OAuth2Interface extends OAuthInterface{
3838
];
3939

4040
/**
41+
* Obtains an OAuth2 access token with the given $code, verifies the $state
42+
* if the provider implements the CSRFToken interface, and returns an AccessToken object
43+
*
4144
* @param string $code
4245
* @param string|null $state
4346
*
4447
* @return \chillerlan\OAuth\Core\AccessToken
48+
* @throws \chillerlan\OAuth\Core\ProviderException
4549
*/
4650
public function getAccessToken(string $code, string $state = null):AccessToken;
4751

4852
/**
53+
* Prepares the URL with optional $params and $scopes which redirects to the provider's authorization prompt
54+
* and returns a PSR-7 UriInterface with all necessary parameters set
55+
*
4956
* @param array|null $params
5057
* @param array|null $scopes
5158
*

‎src/Core/OAuth2Provider.php‎

Lines changed: 5 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -45,10 +45,7 @@ abstract class OAuth2Provider extends OAuthProvider implements OAuth2Interface{
4545
protected $clientCredentialsTokenURL;
4646

4747
/**
48-
* @param array|null $params
49-
* @param array|null $scopes
50-
*
51-
* @return \Psr\Http\Message\UriInterface
48+
* @inheritDoc
5249
*/
5350
public function getAuthURL(array $params = null, array $scopes = null):UriInterface{
5451
$params = $params ?? [];
@@ -115,10 +112,7 @@ protected function parseTokenResponse(ResponseInterface $response):AccessToken{
115112
}
116113

117114
/**
118-
* @param string $code
119-
* @param string|null $state
120-
*
121-
* @return \chillerlan\OAuth\Core\AccessToken
115+
* @inheritDoc
122116
*/
123117
public function getAccessToken(string $code, string $state = null):AccessToken{
124118

@@ -152,11 +146,7 @@ public function getAccessToken(string $code, string $state = null):AccessToken{
152146
}
153147

154148
/**
155-
* @param \Psr\Http\Message\RequestInterface $request
156-
* @param \chillerlan\OAuth\Core\AccessToken $token
157-
*
158-
* @return \Psr\Http\Message\RequestInterface
159-
* @throws \chillerlan\OAuth\Core\ProviderException
149+
* @inheritDoc
160150
*/
161151
public function getRequestAuthorization(RequestInterface $request, AccessToken $token):RequestInterface{
162152

@@ -176,9 +166,7 @@ public function getRequestAuthorization(RequestInterface $request, AccessToken $
176166
}
177167

178168
/**
179-
* @param array $scopes
180-
*
181-
* @return \chillerlan\OAuth\Core\AccessToken
169+
* @inheritDoc
182170
* @throws \chillerlan\OAuth\Core\ProviderException
183171
*/
184172
public function getClientCredentialsToken(array $scopes = null):AccessToken{
@@ -213,9 +201,7 @@ public function getClientCredentialsToken(array $scopes = null):AccessToken{
213201
}
214202

215203
/**
216-
* @param \chillerlan\OAuth\Core\AccessToken $token
217-
*
218-
* @return \chillerlan\OAuth\Core\AccessToken
204+
* @inheritDoc
219205
* @throws \chillerlan\OAuth\Core\ProviderException
220206
*/
221207
public function refreshAccessToken(AccessToken $token = null):AccessToken{

‎src/Core/OAuthInterface.php‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,54 +35,73 @@
3535
interface OAuthInterface extends ApiClientInterface, ClientInterface, LoggerAwareInterface{
3636

3737
/**
38+
* Prepares the URL with optional $params which redirects to the provider's authorization prompt
39+
* and returns a PSR-7 UriInterface with all necessary parameters set
40+
*
3841
* @param array $params
3942
*
4043
* @return \Psr\Http\Message\UriInterface
4144
*/
4245
public function getAuthURL(array $params = null):UriInterface;
4346

4447
/**
48+
* Authorizes the $request with the credentials from the given $token
49+
* and returns a PSR-7 RequestInterface with all necessary headers and/or parameters set
50+
*
4551
* @param \Psr\Http\Message\RequestInterface $request
4652
* @param \chillerlan\OAuth\Core\AccessToken $token
4753
*
4854
* @return \Psr\Http\Message\RequestInterface
55+
* @throws \chillerlan\OAuth\Core\ProviderException
4956
* @internal
5057
*/
5158
public function getRequestAuthorization(RequestInterface $request, AccessToken $token):RequestInterface;
5259

5360
/**
61+
* Prepares an API request to $path with the given parameters, gets authorization, fires the request
62+
* and returns a PSR-7 ResponseInterface with the corresponding API response
63+
*
5464
* @param string $path
5565
* @param array $params
5666
* @param string $method
5767
* @param null $body
5868
* @param array $headers
5969
*
6070
* @return \Psr\Http\Message\ResponseInterface
71+
* @throws \chillerlan\OAuth\Core\ProviderException
6172
*/
6273
public function request(string $path, array $params = null, string $method = null, $body = null, array $headers = null):ResponseInterface;
6374

6475
/**
76+
* Sets an optional OAuthStorageInterface
77+
*
6578
* @param \chillerlan\OAuth\Storage\OAuthStorageInterface $storage
6679
*
6780
* @return \chillerlan\OAuth\Core\OAuthInterface
6881
*/
6982
public function setStorage(OAuthStorageInterface $storage):OAuthInterface;
7083

7184
/**
85+
* Sets an optional PSR-17 RequestFactoryInterface
86+
*
7287
* @param \Psr\Http\Message\RequestFactoryInterface $requestFactory
7388
*
7489
* @return \chillerlan\OAuth\Core\OAuthInterface
7590
*/
7691
public function setRequestFactory(RequestFactoryInterface $requestFactory):OAuthInterface;
7792

7893
/**
94+
* Sets an optional PSR-17 StreamFactoryInterface
95+
*
7996
* @param \Psr\Http\Message\StreamFactoryInterface $streamFactory
8097
*
8198
* @return \chillerlan\OAuth\Core\OAuthInterface
8299
*/
83100
public function setStreamFactory(StreamFactoryInterface $streamFactory):OAuthInterface;
84101

85102
/**
103+
* Sets an optional PSR-17 UriFactoryInterface
104+
*
86105
* @param \Psr\Http\Message\UriFactoryInterface $uriFactory
87106
*
88107
* @return \chillerlan\OAuth\Core\OAuthInterface

‎src/Core/OAuthProvider.php‎

Lines changed: 6 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -187,9 +187,7 @@ public function __get(string $name){
187187
}
188188

189189
/**
190-
* @param \chillerlan\OAuth\Storage\OAuthStorageInterface $storage
191-
*
192-
* @return \chillerlan\OAuth\Core\OAuthInterface
190+
* @inheritDoc
193191
* @codeCoverageIgnore
194192
*/
195193
public function setStorage(OAuthStorageInterface $storage):OAuthInterface{
@@ -199,9 +197,7 @@ public function setStorage(OAuthStorageInterface $storage):OAuthInterface{
199197
}
200198

201199
/**
202-
* @param \Psr\Http\Message\RequestFactoryInterface $requestFactory
203-
*
204-
* @return \chillerlan\OAuth\Core\OAuthInterface
200+
* @inheritDoc
205201
* @codeCoverageIgnore
206202
*/
207203
public function setRequestFactory(RequestFactoryInterface $requestFactory):OAuthInterface{
@@ -211,9 +207,7 @@ public function setRequestFactory(RequestFactoryInterface $requestFactory):OAuth
211207
}
212208

213209
/**
214-
* @param \Psr\Http\Message\StreamFactoryInterface $streamFactory
215-
*
216-
* @return \chillerlan\OAuth\Core\OAuthInterface
210+
* @inheritDoc
217211
* @codeCoverageIgnore
218212
*/
219213
public function setStreamFactory(StreamFactoryInterface $streamFactory):OAuthInterface{
@@ -223,9 +217,7 @@ public function setStreamFactory(StreamFactoryInterface $streamFactory):OAuthInt
223217
}
224218

225219
/**
226-
* @param \Psr\Http\Message\UriFactoryInterface $uriFactory
227-
*
228-
* @return \chillerlan\OAuth\Core\OAuthInterface
220+
* @inheritDoc
229221
* @codeCoverageIgnore
230222
*/
231223
public function setUriFactory(UriFactoryInterface $uriFactory):OAuthInterface{
@@ -316,13 +308,7 @@ protected function cleanBodyParams(array $params):array{
316308
}
317309

318310
/**
319-
* @param string $path
320-
* @param array $params
321-
* @param string $method
322-
* @param mixed $body
323-
* @param array $headers
324-
*
325-
* @return \Psr\Http\Message\ResponseInterface
311+
* @inheritDoc
326312
*/
327313
public function request(string $path, array $params = null, string $method = null, $body = null, array $headers = null):ResponseInterface{
328314

@@ -357,9 +343,7 @@ public function request(string $path, array $params = null, string $method = nul
357343
}
358344

359345
/**
360-
* @param \Psr\Http\Message\RequestInterface $request
361-
*
362-
* @return \Psr\Http\Message\ResponseInterface
346+
* @inheritDoc
363347
*/
364348
public function sendRequest(RequestInterface $request):ResponseInterface{
365349

‎src/Core/TokenRefresh.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,13 @@
1515
interface TokenRefresh{
1616

1717
/**
18+
* Tries to refresh an existing access token with an associated refresh token
19+
* and returns a fresh AccessToken
20+
*
1821
* @param \chillerlan\OAuth\Core\AccessToken|null $token
1922
*
2023
* @return \chillerlan\OAuth\Core\AccessToken
24+
* @throws \chillerlan\OAuth\Core\ProviderException
2125
*/
2226
public function refreshAccessToken(AccessToken $token = null):AccessToken;
2327

0 commit comments

Comments
 (0)