PHPStan error when using authenticate with ClientCredentialsGrant

[treyssatvincent]

Hello, with the following code:

// $pendingRequest is a \Saloon\Http\PendingRequest
// $connector is an implementation of \Saloon\Http\Connector that uses \Saloon\Traits\OAuth2\ClientCredentialsGrant
$pendingRequest->authenticate($connector->getAccessToken());

PHPStan will detect it as a possible bug:

Parameter #1 $authenticator of method Saloon\Http\PendingRequest::authenticate() expects Saloon\Contracts\Authenticator,
Saloon\Contracts\OAuthAuthenticator|Saloon\Http\Response given.

And indeed if getAccessToken returns a Response, authenticate would crash.

By using conditional return types in the PHPDoc we can tell that the return type is either a OAuthAuthenticator or a Response:

/**
 * Get the access token
 *
 * @template TRequest of \Saloon\Http\Request
 *
 * @param array<string> $scopes
 * @param callable(TRequest): (void)|null $requestModifier
 * @return ($returnResponse is true ? Response : OAuthAuthenticator)
 */
public function getAccessToken(array $scopes = [], string $scopeSeparator = ' ', bool $returnResponse = false, ?callable $requestModifier = null): OAuthAuthenticator|Response

(here's a commit of this change: https://github.com/treyssatvincent/saloon/commit/724ad17a5fc475d66fd9bb8ad5e61eebb0f5580b)

I can open a pull request if that's something you'll want.

I wasn't sure that the sentence "please first discuss the change you wish to make via issue, email, or any other method" from CONTRIBUTING.md allowed me to create the pull request with the text I included here as description, if it was then I'm sorry for the extra step!

[treyssatvincent]

I should have looked in opened pull requests, it's already right here: https://github.com/saloonphp/saloon/pull/516#pullrequestreview-3384340812