OAuth2.0 documentation feedback

[boryn]

First, I just must say this is an exceptionally great package, perfectly thought out and with great scalability. WOW!

I have some feedback on the documentation, in the places where I got blocked during the implementation. When looking at https://docs.saloon.dev/digging-deeper/oauth2-authentication#refreshing-access-tokens, there is:

$authenticator = $user->auth; // Your authenticator class.

which makes me think, what the heck is $user->auth??? Is this a field? Is this a relationship? What have I missed?

I bet it would be more clear if the field was named authenticator and comment was something like this:
// $authenticator stored in the model using OAuthAuthenticatorCast or EncryptedOAuthAuthenticatorCast

Later, the docs at https://docs.saloon.dev/digging-deeper/oauth2-authentication#building-a-method-to-create-an-authenticated-instance-of-your-sdk show the spotify() method example. But within this, there should be no $user-> but $this-> as we are already in the User class.

PS. I would as well suggest splitting this method into two for better readability:

public function spotify(): SpotifyApiConnector
{
    $authenticator = $this->refreshAccessToken($this->spotify_authenticator);

    $spotify = new SpotifyApiConnector();
    $spotify->authenticate($authenticator);

    return $spotify;
}

public function refreshAccessToken(
    OAuthAuthenticator $authenticator,
    $forceRefresh = false
): OAuthAuthenticator {
    if ($authenticator->hasExpired() || $forceRefresh) {
        $authenticator = SpotifyAuthConnector::make()->refreshAccessToken($authenticator);

        $this->spotify_authenticator = $authenticator;
        $this->save();
    }

    return $authenticator;
}

[Sammyjo20]

Hey @boryn

Many thanks for your suggestions around the documentation - I totally understand that it looks a little confusing. I'm going to amend the docs so they read better and don't feel so cluttered.

I'm also going to be writing the docs for the client credentials grant so I will give this whole section a reread and work out where else we can improve 🔥

[boryn]

Hi @Sammyjo20!

Found another place, where it would be good to add some details. After looking at source code, I have found out that we can pass key name while fetching response as an array or collection:
$response->json('data')
$response->collect('data')

The documentation at https://docs.saloon.dev/the-basics/responses does not mention this.

BTW. ->json() is a little bit misleading, as actually we receive an array. Maybe it would be good to have an alias ->array() to this method? Or even let json return a json string and array an array, but then it would be a breaking change.

[boryn]

The examples at https://docs.saloon.dev/digging-deeper/pagination contain $paginator->setCurrentOffset(1000); but this method seems to be not implemented.

Examples should not contain semicolon at the end of methods,
e.g.: public function paginate(Request $request, mixed ...$additionalArguments): OffsetPaginator;

[Sammyjo20]

Hey @boryn just wanted to let you know that I've re-written the section on the authorization code grant: https://docs.saloon.dev/digging-deeper/oauth2-authentication/oauth2-authentication

Let me know your feedback and if it reads better :D I'm going in to write the documentation on the client credentials grant.

[Sammyjo20]

I'm going to close this for now, please can we discuss future documentation improvements as discussions as they are better suited (with replies and threads)

Cheers @boryn as ever!