Add OAuth Access Token Management to ClientHandler

[Thavarshan]

Description

Currently, the ClientHandler class requires developers to handle OAuth access token management externally. This feature request proposes adding functionality to automatically obtain and store an OAuth access token during the instantiation of ClientHandler, or reuse an existing one if available in the session.

Proposed Feature Details

• New Behavior: When the ClientHandler class is instantiated with client_id and client_secret in the options array, it should:
  1. Automatically make a request to the token endpoint to retrieve an OAuth access token.
  2. Store the token in the session for subsequent use, avoiding redundant token requests.
  3. Check the session for an existing valid token before requesting a new one.

Example Syntax

// Instantiation with OAuth credentials
$clientHandler = new ClientHandler(options: [
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret'
]);

// Expected behavior:
// - Automatically fetches and stores an OAuth access token in the session
// - Reuses the token for subsequent requests

Benefits

• Improved Developer Experience: Reduces the complexity of handling OAuth token management, allowing developers to focus on core functionality.
• Efficiency: Minimizes redundant token requests by reusing valid tokens stored in the session.
• Security: Encourages best practices for storing tokens securely and ensures proper handling of sensitive credentials.

Additional Considerations

• Configuration Options: Allow developers to customize OAuth settings (e.g., token endpoint URL, scopes, token expiration handling).
• Token Validation: Check the validity of the stored token (e.g., expiration) before reuse.
• Session Management: Use PHP sessions or a configurable storage mechanism for token persistence.
• Backward Compatibility: Ensure existing functionality remains unaffected for developers not using OAuth.
• Documentation: Update the documentation with details on:
  • Required parameters (client_id, client_secret).
  • How the token management flow works.
  • Example use cases.

Proposed Workflow

1. Instantiation: When a new ClientHandler is created with client_id and client_secret, the library:
   • Checks the session for an existing token.
   • If no token is found or the token has expired, it makes a request to the token endpoint.
2. Token Reuse: The stored token is automatically used for subsequent requests.
3. Automatic Refresh (Optional): If supported by the API, refresh the token when expired.