friendship ended with social-app. php is my new best friend
veryroundbird.house
1<?php
2/**
3 * Interface OAuthInterface
4 *
5 * @created 09.07.2017
6 * @author Smiley <smiley@chillerlan.net>
7 * @copyright 2017 Smiley
8 * @license MIT
9 */
10declare(strict_types=1);
11
12namespace chillerlan\OAuth\Core;
13
14use chillerlan\OAuth\Storage\OAuthStorageInterface;
15use Psr\Http\Client\ClientInterface;
16use Psr\Log\LoggerInterface;
17use Psr\Http\Message\{
18 RequestFactoryInterface, RequestInterface, ResponseInterface,
19 StreamFactoryInterface, StreamInterface, UriFactoryInterface, UriInterface
20};
21
22/**
23 * Specifies the basic methods for an OAuth provider.
24 */
25interface OAuthInterface extends ClientInterface{
26
27 /**
28 * A common user agent string that can be used in requests
29 *
30 * @var string
31 */
32 public const USER_AGENT = 'chillerlanPhpOAuth/1.0.0 +https://github.com/chillerlan/php-oauth';
33
34 /**
35 * An identifier for the provider, usually the class name in ALLCAPS (required)
36 *
37 * @var string
38 */
39 public const IDENTIFIER = '';
40
41 /**
42 * additional headers to use during authentication
43 *
44 * Note: must not contain: Accept-Encoding, Authorization, Content-Length, Content-Type
45 *
46 * @var array<string, string>
47 */
48 public const HEADERS_AUTH = [];
49
50 /**
51 * additional headers to use during API access
52 *
53 * Note: must not contain: Authorization
54 *
55 * @var array<string, string>
56 */
57 public const HEADERS_API = [];
58
59 /**
60 * Default scopes to apply if none were provided via the $scopes parameter
61 *
62 * @var string[]
63 */
64 public const DEFAULT_SCOPES = [];
65
66 /**
67 * The delimiter string for scopes
68 *
69 * @var string
70 */
71 public const SCOPES_DELIMITER = ' ';
72
73 /**
74 * Returns the name of the provider/class
75 */
76 public function getName():string;
77
78 /**
79 * Returns the link to the provider's API docs, or null if the value is not set
80 */
81 public function getApiDocURL():string|null;
82
83 /**
84 * Returns the link to the provider's credential registration/application page, or null if the value is not set
85 */
86 public function getApplicationURL():string|null;
87
88 /**
89 * Returns the link to the page where a user can revoke access tokens, or null if the value is not set
90 */
91 public function getUserRevokeURL():string|null;
92
93 /**
94 * Prepares the URL with optional $params which redirects to the provider's authorization prompt
95 * and returns a PSR-7 UriInterface with all necessary parameters set.
96 *
97 * If the provider supports RFC-9126 "Pushed Authorization Requests (PAR)", a request to the PAR endpoint
98 * shall be made within this method in order to send authorization data and obtain a temporary request URI.
99 *
100 * @link https://datatracker.ietf.org/doc/html/rfc5849#section-2.2
101 * @link https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
102 * @link https://datatracker.ietf.org/doc/html/rfc9126
103 * @see \chillerlan\OAuth\Core\PAR
104 *
105 * @param array<string, scalar>|null $params
106 * @param string[]|null $scopes
107 */
108 public function getAuthorizationURL(array|null $params = null, array|null $scopes = null):UriInterface;
109
110 /**
111 * Authorizes the $request with the credentials from the given $token
112 * and returns a PSR-7 RequestInterface with all necessary headers and/or parameters set
113 *
114 * @see \chillerlan\OAuth\Core\OAuthProvider::sendRequest()
115 */
116 public function getRequestAuthorization(RequestInterface $request, AccessToken|null $token = null):RequestInterface;
117
118 /**
119 * Prepares an API request to $path with the given parameters, gets authorization, fires the request
120 * and returns a PSR-7 ResponseInterface with the corresponding API response
121 *
122 * @param array<string, scalar|bool|null>|null $params
123 * @param StreamInterface|array<string, scalar|bool|null>|string|null $body
124 * @param array<string, string>|null $headers
125 */
126 public function request(
127 string $path,
128 array|null $params = null,
129 string|null $method = null,
130 StreamInterface|array|string|null $body = null,
131 array|null $headers = null,
132 string|null $protocolVersion = null,
133 ):ResponseInterface;
134
135 /**
136 * Sets an optional OAuthStorageInterface
137 */
138 public function setStorage(OAuthStorageInterface $storage):static;
139
140 /**
141 * Returns the current OAuthStorageInterface
142 */
143 public function getStorage():OAuthStorageInterface;
144
145 /**
146 * Sets an access token in the current OAuthStorageInterface (shorthand/convenience)
147 */
148 public function storeAccessToken(AccessToken $token):static;
149
150 /**
151 * Gets an access token from the current OAuthStorageInterface (shorthand/convenience)
152 */
153 public function getAccessTokenFromStorage():AccessToken;
154
155 /**
156 * Sets an optional PSR-3 LoggerInterface
157 */
158 public function setLogger(LoggerInterface $logger):static;
159
160 /**
161 * Sets an optional PSR-17 RequestFactoryInterface
162 */
163 public function setRequestFactory(RequestFactoryInterface $requestFactory):static;
164
165 /**
166 * Sets an optional PSR-17 StreamFactoryInterface
167 */
168 public function setStreamFactory(StreamFactoryInterface $streamFactory):static;
169
170 /**
171 * Sets an optional PSR-17 UriFactoryInterface
172 */
173 public function setUriFactory(UriFactoryInterface $uriFactory):static;
174
175}