Beta Release 0.5.0 (#3)

* Automated commit message * Automated commit message * Automated commit message * Automated commit message --------- Co-authored-by: PayPalServerSDKs <server-sdks@paypal.com>
2024-09-09 12:10:34 -05:00
parent c9cb1ad04a
commit 6b43a4225b
732 changed files with 73569 additions and 1 deletions
--- a/doc/auth/oauth-2-client-credentials-grant.md
+++ b/doc/auth/oauth-2-client-credentials-grant.md
@@ -0,0 +1,88 @@
+
+# OAuth 2 Client Credentials Grant
+
+
+
+Documentation for accessing and setting credentials for Oauth2.
+
+## Auth Credentials
+
+| Name | Type | Description | Setter | Getter |
+|  --- | --- | --- | --- | --- |
+| OAuthClientId | `string` | OAuth 2 Client ID | `oAuthClientId` | `getOAuthClientId()` |
+| OAuthClientSecret | `string` | OAuth 2 Client Secret | `oAuthClientSecret` | `getOAuthClientSecret()` |
+| OAuthToken | `OAuthToken\|null` | Object for storing information about the OAuth token | `oAuthToken` | `getOAuthToken()` |
+| OAuthClockSkew | `int` | Clock skew time in seconds applied while checking the OAuth Token expiry. | `oAuthClockSkew` | - |
+| OAuthTokenProvider | `callable(OAuthToken, ClientCredentialsAuthManager): OAuthToken` | Registers a callback for oAuth Token Provider used for automatic token fetching/refreshing. | `oAuthTokenProvider` | - |
+| OAuthOnTokenUpdate | `callable(OAuthToken): void` | Registers a callback for token update event. | `oAuthOnTokenUpdate` | - |
+
+
+
+**Note:** Auth credentials can be set using `ClientCredentialsAuthCredentialsBuilder::init()` in `clientCredentialsAuthCredentials` method in the client builder and accessed through `getClientCredentialsAuth` method in the client instance.
+
+## Usage Example
+
+### Client Initialization
+
+You must initialize the client with *OAuth 2.0 Client Credentials Grant* credentials as shown in the following code snippet. This will fetch the OAuth token automatically when any of the endpoints, requiring *OAuth 2.0 Client Credentials Grant* autentication, are called.
+
+```php
+$client = PaypalServerSDKClientBuilder::init()
+    ->clientCredentialsAuthCredentials(
+        ClientCredentialsAuthCredentialsBuilder::init(
+            'OAuthClientId',
+            'OAuthClientSecret'
+        )
+    )
+    ->build();
+```
+
+
+
+Your application can also manually provide an OAuthToken using the setter `oAuthToken` in `ClientCredentialsAuthCredentialsBuilder` object. This function takes in an instance of OAuthToken containing information for authorizing client requests and refreshing the token itself.
+
+### Adding OAuth Token Update Callback
+
+Whenever the OAuth Token gets updated, the provided callback implementation will be executed. For instance, you may use it to store your access token whenever it gets updated.
+
+```php
+$client = PaypalServerSDKClientBuilder::init()
+    ->clientCredentialsAuthCredentials(
+        ClientCredentialsAuthCredentialsBuilder::init(
+            'OAuthClientId',
+            'OAuthClientSecret'
+        )
+            ->oAuthOnTokenUpdate(
+                function (OAuthToken $oAuthToken): void {
+                    // Add the callback handler to perform operations like save to DB or file etc.
+                    // It will be triggered whenever the token gets updated.
+                    $this->saveTokenToDatabase($oAuthToken);
+                }
+            )
+    )
+    ->build();
+```
+
+### Adding Custom OAuth Token Provider
+
+To authorize a client using a stored access token, set up the `oAuthTokenProvider` in `ClientCredentialsAuthCredentialsBuilder` along with the other auth parameters before creating the client:
+
+```php
+$client = PaypalServerSDKClientBuilder::init()
+    ->clientCredentialsAuthCredentials(
+        ClientCredentialsAuthCredentialsBuilder::init(
+            'OAuthClientId',
+            'OAuthClientSecret'
+        )
+            ->oAuthTokenProvider(
+                function (?OAuthToken $lastOAuthToken, ClientCredentialsAuthManager $authManager): OAuthToken {
+                    // Add the callback handler to provide a new OAuth token.
+                    // It will be triggered whenever the lastOAuthToken is null or expired.
+                    return $this->loadTokenFromDatabase() ?? $authManager->fetchToken();
+                }
+            )
+    )
+    ->build();
+```
+
+