README

This library is a simple, easy implement OAuth2 client for SteemConnect V2 clients.

It takes the pain from integrating and parsing all the specifics and delivers a great authorization flow for those who aim to handle authorization through SteemConnect V2.

0. Why?

Well, OAuth2 is not that complicated, this project started while building a SteemConnect V2 SDK for PHP, so this project is the Authorization part of another package coming on the next days.

1. Installation.

All you need to do is install this library as a dependency on your project, through composer:

composer require hernandev/oauth2-sc2

2. Usage:

Before using thins library, keep in mind you'll need a SteemConnect application client ID and secret.

2.1. Configuring:

It could not be more simple. Just create a config instance, passing your application credentials:

use SteemConnect\OAuth2\Config\Config;

// creates the configuration object:
$config = new Config('your.app', 'your-long-secret-id-here-keep-it-secret');

After setting your credentials, you will need to decide with scopes you will ask permission to:

// set the scopes you want.
$config->setScopes([
    'login', 'vote', 'comment', 'comment_delete'
]);

If you are not sure about the scopes you will need, those are documented on the SteemConnect wiki.

Finally, we will configure, to which URL the user should return, after granting you the permissions:

// set the return / callback URL.
$config->setReturnUrl('https://my-steem-app-is-awesome.com/login/return');

2.2. Redirecting to Authorization:

That was really, all you need to configure to use the library, pretty cool ham?

Now, of course, you need to redirect the users, to SteemConnect where they will authorize you to act on their behalf.

use SteemConnect\OAuth2\Provider\Provider;

// first, we create a provider instance, passing the configuration needed:
$provider = new Provider($config);

// finally, we can get the redirect URL, so we can send users to SteemConnect:

// get the URL string that you will redirect to.
$provider->getAuthorizationUrl()

2.3. Parsing the Return:

Guess what? super hard to do:

You will need both the config and provider code used before, so I assume you will be clever and put that logic on a common place.

// just call the parse return URL and this library will automatically exchange the access code by the actual token: 
$token = $provider->parseReturn();

On the previous call, $token is an instance of AccessToken class, which can be used for the following things:

// gets the actual token that will be used on requests.
$token->getToken();

// gets the expiration date, so you know the token is no longer valid.
$token->getExpires();

// gets the refresh token, which may be used to issue a new token, if the offline scope was requested.
$token->getRefreshToken();

// gets the standard ID for the account authorizing your app, it means, this field retrieves the account @username
$token->getResourceOwnerId();

2.4. Storing Tokens.

After obtained a given user's Access Token, in most cases, you will need to store the tokens for later usage.

Whatever the approach for storing the tokens (browser session / database), you will need to serialize the tokens and later, decode then.

This can be easily done, by two methods on the Provider:

Encoding:

// encode the AccessToken instance into a JSON string.
$tokenJson = $provider->encodeToken($token);

Decoding:

// decode the JSON string token back into a AccessToken instance.
$token = $provider->decodeToken($tokenJson);

2.5. Refreshing Expired Tokens.

Whenever the offline scope is used to issue a token, the resulting AccessToken instance will contain a field called `refresh_token. The refresh token can be used for issuing a new one.

To issue a new token, using a existing one, that contains a refresh token, just do:

// get a new token from the existing / expired one.
$newToken = $provider->refreshToken($token);

If you only stored the refresh_token field value, you may use that string directly, by doing:

// get a new AccessToken using the refresh token string.
$token = $provider->refreshTokenString($refreshTokenString);

2.5. Extras:

Of course there are extras!

This library implements the ResourceOwner interface, which means you can also query right away some information about the account which granted you permissions:

// gets the resource owner instance.
$owner = $provider->getResourceOwner($token);

// now you can use any key you may see on steemd.com directly on that $owner object!!!

$owner->profile_json;
$owner->balance;
$owner->reputation;
// and so on...

That's All Folks!

hernandev / oauth2-sc2

Maintainers

Details