OAuth that just works !
This SDK allows you to use OAuth.io from a PHP backend, to handle the authentication and API calls from your server instead of from your front-end, for 100+ API providers.
The current version of the SDK is 0.3.2. Older versions are deprecated.
You can also get nightlies by checking out our develop branch.
To get more information about this SDK and its method, please refer to its reference documentation on OAuth.io.
- Server-side OAuth authentication flow
- Requests to API from the backend
- Unified user information (
.me()method) requests when available - Access token renewal with the refresh_token when available
You don't want to use APIs directly from the front-end, but rather through web-services inside your PHP backend.
First of all, you'll need to set your app's backend to PHP in your OAuth.io dashboard.
This allows you to get a refresh token from the provider if available.
You can install it through Composer by adding the following dependency to your composer.json :
"require": {
...
"oauth-io/oauth": "0.3.0"
...
},Then run in the console :
$ composer installThe OAuth class is stored in the OAuth_io namespace. You need to include it in your file like this (make sure you have required the Composer autoloader file):
<?php
require_once '/path/to/autoload.php';
use OAuth_io\OAuth;
//?>PSR-0 support
If you're using Composer with an autoloader, you can use the PSR-0 notation to use this package. Just put the following code at the top of your script :
<?php
use OAuth_io\OAuth;
//?>Initialization
To initialize the SDK, you have to give it your OAuth.io's app's key and secret (you can grab them on the oauth.io Key-Manager) :
<?php
$oauth = new OAuth();
$oauth->initialize('your_key', 'your_secret');
//?>Note on session
You can give your own managed session array to the constructor so that if you already have a session manager, the SDK doesn't mess around with it :
<?php
$_SESSION['some_subarray_in_the_session'] = array();
$myarray = $_SESSION['some_subarray_in_the_session'];
$oauth = new OAuth($myarray);
//?>Note on certificates
If you're using oauthd (the open source version of oauth.io) and that you don't have a verified ssl certificate yet (you should in the future if you want to put your code in production), you can disable the SSL certificate verification like this :
<?php
$oauth = new OAuth(null, false);
//?>Authenticating the user
The first thing you need to do is to create an endpoint that will redirect your user to the provider's authentication page, so that the user can accept the permissions your app needs.
In this endpoint, call the redirect method like this:
$oauth->redirect('the_provider', '/callback/url');This will automatically redirect your user to the provider's website. Once he has accepted the permissions, he will be redirected to the '/callback/url' on your app, where you'll be able to retrieve a request object.
In an endpoint associated to the '/callback/url', call the auth method with the redirect option set to true to get a request object, like this:
$request_object = $oauth->auth('the_provider', array(
'redirect' => true
));$request_object is an object that allows you to perform requests (see further down to learn how to), and that contains the user's credentials.
Using the session to get a request object
Usually, you'll want to make calls to the API several times while the user is connected to your app. Once you've authenticated the user once with a code, the session is automatically configured to work with the SDK.
Thus, you just need to do this to get a request object:
$request_object = $oauth->auth('the_provider');Saving credentials to re-generate a request object
You can also save the user's credentials to make requests in a cron. You can get the credentials array from a request object like this :
$credentials = $request_object->getCredentials();
// Here save the $credentials array for later useThen, when you want to reuse these credentials, you can rebuild a $request_object from them:
$request_object = $oauth->auth('the_provider', array(
'credentials' => $credentials
));Making requests to the API
Once you have a request object, you can make requests to the API.
<?php
$response_GET = $request_object->get('https://theprovider.com/api/endpoint');
$response_POST = $request_object->post('https://theprovider.com/api/endpoint', array('some' => 'data'));
$response_PUT = $request_object->put('https://theprovider.com/api/endpoint', array('some' => 'data'));
$response_DELETE = $request_object->del('https://theprovider.com/api/endpoint');
$response_PATCH = $request_object->patch('https://theprovider.com/api/endpoint', array('some' => 'data'));
//?>You can also call the me(array $filters) method from that request object. This method returns a unified array containing information about the user.
<?php
$facebook_requester = $oauth->auth('facebook', array(
'redirect' => true
));
$result = $facebook_requester->me(array('firstname', 'lastname', 'email'));
// you'll have $result["firstname"], $result["lastname"] and $result["email"] set with the user's facebook information.
//?>You can refer to the OAuth.io me() feature to get more information about the fields that are returned by this method.
Refreshing the token
If a refresh token is available and the access token is expired, the auth method will automatically use that refresh token to get a new access token.
You can force the renewal by passing the force_refresh field in the options array:
$request_object = $oauth->auth('the_provider', array(
'credentials' => $credentials,
'force_refresh' => true
));You can also directly refresh a credentials array like this:
$refreshed_credentials = $oauth->refreshCredentials($old_credentials);Issues
Please discuss issues and features on Github Issues. We'll be happy to answer to your questions and improve the SDK based on your feedback.
Pull requests
You are welcome to fork and make pull requests. We appreciate the time you spend working on this project and we will be happy to review your code and merge it if it brings nice improvements :)
If you want to do a pull request, please mind these simple rules :
- One feature per pull request
- Write clear commit messages
- Unit test your feature : if it's a bug fix for example, write a test that proves the bug exists and that your fix resolves it.
- Write a clear description of the pull request
If you do so, we'll be able to merge your pull request more quickly :)
The SDK is written as a Composer module. You can install its dependencies like this :
sdk/folder$ composer installWe use PHPUnit to test the SDK. To test it, just run the following from the SDK root folder :
$ ./vendor/phpunit/phpunit/phpunitThe SDK is released under the Apache2 license.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent