Update README.md
Phil Sturgeon
parent
925e47b480
commit
a3ea33f2c5
175
README.md
175
README.md
|
|
@ -1,75 +1,27 @@
|
|||
# OAuth 2.0 Client Library
|
||||
# OAuth 2.0 Client
|
||||
|
||||
[](https://travis-ci.org/thephpleague/oauth2-client)
|
||||
[](https://packagist.org/packages/league/oauth2-client)
|
||||
[](https://packagist.org/packages/league/oauth2-client)
|
||||
|
||||
This library makes it stupidly simple to integrate your application with OAuth 2.0 identity providers. It has built in support for:
|
||||
Everyone is used to seeing those "Connect with Facebook/Google/etc" buttons around the Internet and social network
|
||||
integration is an important feature of most web-apps these days. Many of these sites use an Authentication and Authorization standard called OAuth 2.0.
|
||||
|
||||
* Eventbrite
|
||||
* Facebook
|
||||
* Github
|
||||
* Google
|
||||
* Instagram
|
||||
* LinkedIn
|
||||
* Microsoft
|
||||
* Vkontakte
|
||||
It will work with any OAuth 2.0 provider (be it your own [PHP OAuth 2.0 Server] or Facebook) and provides support for
|
||||
popular systems out of the box. This package abstracts out some of the subtle but important differences between various providers, handles access tokens and refresh tokens, and allows you easy access to profile information on these other sites.
|
||||
|
||||
Adding support for other providers is trivial.
|
||||
This package is compliant with [PSR-1][], [PSR-2][] and [PSR-4][]. If you notice compliance oversights, please send
|
||||
a patch via pull request.
|
||||
|
||||
The library requires PHP 5.4+ and is PSR-4 compatible.
|
||||
[PSR-1]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md
|
||||
[PSR-2]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md
|
||||
[PSR-4]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md
|
||||
|
||||
## Usage
|
||||
|
||||
```php
|
||||
$provider = new League\OAuth2\Client\Provider\<provider name>(array(
|
||||
'clientId' => 'XXXXXXXX',
|
||||
'clientSecret' => 'XXXXXXXX',
|
||||
'redirectUri' => 'http://your-registered-redirect-uri/'
|
||||
));
|
||||
|
||||
if ( ! isset($_GET['code'])) {
|
||||
|
||||
// If we don't have an authorization code then get one
|
||||
$provider->authorize();
|
||||
|
||||
} else {
|
||||
|
||||
try {
|
||||
|
||||
// Try to get an access token (using the authorization code grant)
|
||||
$t = $provider->getAccessToken('authorization_code', array('code' => $_GET['code']));
|
||||
|
||||
// NOTE: If you are using Eventbrite you will need to add the grant_type parameter (see below)
|
||||
// $t = $provider->getAccessToken('authorization_code', array('code' => $_GET['code'], 'grant_type' => 'authorization_code'));
|
||||
|
||||
try {
|
||||
|
||||
// We got an access token, let's now get the user's details
|
||||
$userDetails = $provider->getUserDetails($t);
|
||||
|
||||
foreach ($userDetails as $attribute => $value) {
|
||||
var_dump($attribute, $value) . PHP_EOL . PHP_EOL;
|
||||
}
|
||||
|
||||
} catch (Exception $e) {
|
||||
|
||||
// Failed to get user details
|
||||
|
||||
}
|
||||
|
||||
} catch (Exception $e) {
|
||||
|
||||
// Failed to get access token
|
||||
// If you have a refesh token you can use it here:
|
||||
$grant = new \League\OAuth2\Client\Grant\RefreshToken();
|
||||
$t = $provider->getAccessToken($grant, array('refresh_token' => $refreshToken));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Built-In Providers
|
||||
|
||||
This package currently has built-in support for:
|
||||
|
||||
- Eventbrite
|
||||
- Facebook
|
||||
- Github
|
||||
|
|
@ -81,15 +33,111 @@ if ( ! isset($_GET['code'])) {
|
|||
These are as many OAuth 2 services as we plan to support officially. Maintaining a wide selection of providers
|
||||
damages our ability to make this package the best it can be, especially as we progress towards v1.0.
|
||||
|
||||
### Third-Party Providers
|
||||
|
||||
If you would like to support other providers, please make them available as a Composer package, then link to them
|
||||
below.
|
||||
|
||||
### Third-Party Providers
|
||||
|
||||
These providers allow integration with other providers not supported by `oauth2-client`. They may require an older version
|
||||
so please help them out with a pull request if you notice this.
|
||||
|
||||
- _< insert providers here >_
|
||||
- _Insert providers here_
|
||||
|
||||
## Install
|
||||
|
||||
Via Composer
|
||||
|
||||
``` json
|
||||
{
|
||||
"require": {
|
||||
"league/oauth2-client": "~0.3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
The following versions of PHP are supported.
|
||||
|
||||
* PHP 5.4
|
||||
* PHP 5.5
|
||||
* PHP 5.6
|
||||
* HHVM
|
||||
|
||||
## Usage
|
||||
|
||||
### Authorization Code Flow
|
||||
|
||||
```php
|
||||
$provider = new League\OAuth2\Client\Provider\<ProviderName>(array(
|
||||
'clientId' => 'XXXXXXXX',
|
||||
'clientSecret' => 'XXXXXXXX',
|
||||
'redirectUri' => 'https://your-registered-redirect-uri/'
|
||||
));
|
||||
|
||||
if ( ! isset($_GET['code'])) {
|
||||
|
||||
// If we don't have an authorization code then get one
|
||||
header('Location: '.$provider->getAuthorizationUrl());
|
||||
exit;
|
||||
|
||||
} else {
|
||||
|
||||
// Try to get an access token (using the authorization code grant)
|
||||
$token = $provider->getAccessToken('authorization_code', [
|
||||
'code' => $_GET['code']
|
||||
]);
|
||||
|
||||
// If you are using Eventbrite you will need to add the grant_type parameter (see below)
|
||||
$token = $provider->getAccessToken('authorization_code', [
|
||||
'code' => $_GET['code'],
|
||||
'grant_type' => 'authorization_code'
|
||||
]);
|
||||
|
||||
// Optional: Now you have a token you can look up a users profile data
|
||||
try {
|
||||
|
||||
// We got an access token, let's now get the user's details
|
||||
$userDetails = $provider->getUserDetails($token);
|
||||
|
||||
// Use these details to create a new profile
|
||||
printf('Hello %s!', $userDetails->firstName);
|
||||
|
||||
} catch (Exception $e) {
|
||||
|
||||
// Failed to get user details
|
||||
exit('Oh dear...');
|
||||
}
|
||||
|
||||
// Use this to interact with an API on the users behalf
|
||||
echo $token->access_token;
|
||||
|
||||
// Use this to get a new access token if the old one expires
|
||||
echo $token->refresh_token;
|
||||
|
||||
// Number of seconds until the access token will expire, and need refreshing
|
||||
echo $token->expires_in;
|
||||
}
|
||||
```
|
||||
|
||||
### Refreshing a Token
|
||||
|
||||
```php
|
||||
$provider = new League\OAuth2\Client\Provider\<ProviderName>(array(
|
||||
'clientId' => 'XXXXXXXX',
|
||||
'clientSecret' => 'XXXXXXXX',
|
||||
'redirectUri' => 'https://your-registered-redirect-uri/'
|
||||
));
|
||||
|
||||
$grant = new \League\OAuth2\Client\Grant\RefreshToken();
|
||||
$token = $provider->getAccessToken($grant, ['refresh_token' => $refreshToken]);
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
``` bash
|
||||
$ phpunit
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
|
|
@ -97,4 +145,3 @@ The MIT License (MIT). Please see [License File](https://github.com/thephpleague
|
|||
|
||||
|
||||
[](https://bitdeli.com/free "Bitdeli Badge")
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue