Elgg-Lorea-Hydra/mod/gnusocial_api/vendors/gnusocialoauth/README

GNUSocialOAuth
------------

PHP library for working with GNUSocial's OAuth API.

Flow Overview
=============

1. Build GNUSocialOAuth object using client credentials.
2. Request temporary credentials from GNUSocial.
3. Build authorize URL for GNUSocial.
4. Redirect user to authorize URL.
5. User authorizes access and returns from GNUSocial.
6. Rebuild GNUSocialOAuth object with client credentials and temporary credentials.
7. Get token credentials from GNUSocial.
8. Rebuild GNUSocialOAuth object with client credentials and token credentials.
9. Query GNUSocial API.

Terminology
===========

The terminology has changed since 0.1.x to better match the draft-hammer-oauth IETF
RFC. You can read that at http://tools.ietf.org/html/draft-hammer-oauth. Some of the
terms will differ from those GNUSocial uses as well.

client credentials - Consumer key/secret you get when registering an app with GNUSocial.
temporary credentials - Previously known as the request token.
token credentials - Previously known as the access token.

Parameters
==========

There are a number of parameters you can modify after creating a GNUSocialOAuth object.

Switch an existing GNUSocialOAuth install to use version 1.1 of the API.

    $connection->$host = "https://gnusocial.org/api/";

Custom useragent.

    $connection->useragent = 'Custom useragent string';

Verify GNUSocials SSL certificate.

    $connection->ssl_verifypeer = TRUE;

There are several more you can find in GNUSocialOAuth.php.

Extended flow using example code
================================

To use GNUSocialOAuth with the GNUSocial API you need *GNUSocialOAuth.php*, *OAuth.php* and
client credentials. You can get client credentials by registering your application at gnusocial apps.

Users start out on connect.php which displays the "Sign in with GNUSocial" image hyperlinked
to redirect.php. This button should be displayed on your homepage in your login section. The
client credentials are saved in config.php as `CONSUMER_KEY` and `CONSUMER_SECRET`. You can
save a static callback URL in the app settings page, in the config file or use a dynamic
callback URL later in step 2. In example use https://example.com/callback.php.

1) When a user lands on redirect.php we build a new GNUSocialOAuth object using the client credentials.
If you have your own configuration method feel free to use it instead of config.php.

    $connection = new GNUSocialOAuth(CONSUMER_KEY, CONSUMER_SECRET); // Use config.php client credentials
    $connection = new GNUSocialOAuth('abc890', '123xyz');

2) Using the built $connection object you will ask GNUSocial for temporary credentials. The `oauth_callback` value is required.

    $temporary_credentials = $connection->getRequestToken(OAUTH_CALLBACK); // Use config.php callback URL.

3) Now that we have temporary credentials the user has to go to GNUSocial and authorize the app
to access and updates their data. You can also pass a second parameter of FALSE to not use [Sign
in with GNUSocial].

    $redirect_url = $connection->getAuthorizeURL($temporary_credentials); // Use Sign in with GNUSocial
    $redirect_url = $connection->getAuthorizeURL($temporary_credentials, FALSE);

4) You will now have a GNUSocial URL that you must send the user to.

    https://gnusocial.org/api/oauth/authenticate?oauth_token=xyz123

5) The user is now on gnusocial.net and may have to login. Once authenticated with GNUSocial they will
will either have to click on allow/deny, or will be automatically redirected back to the callback.

6) Now that the user has returned to callback.php and allowed access we need to build a new
GNUSocialOAuth object using the temporary credentials.

    $connection = new GNUSocialOAuth(CONSUMER_KEY, CONSUMER_SECRET, $_SESSION['oauth_token'],
    $_SESSION['oauth_token_secret']);

7) Now we ask GNUSocial for long lasting token credentials. These are specific to the application
and user and will act like password to make future requests. Normally the token credentials would
get saved in your database but for this example we are just using sessions.

    $token_credentials = $connection->getAccessToken($_REQUEST['oauth_verifier']);

8) With the token credentials we build a new GNUSocialOAuth object.

    $connection = new GNUSocialOAuth(CONSUMER_KEY, CONSUMER_SECRET, $token_credentials['oauth_token'],
    $token_credentials['oauth_token_secret']);

9) And finally we can make requests authenticated as the user. You can GET, POST, and DELETE API
methods. Directly copy the path from the API documentation and add an array of any parameter
you wish to include for the API method such as curser or in_reply_to_status_id.

    $account = $connection->get('account/verify_credentials');
    $status = $connection->post('statuses/update', array('status' => 'Text of status here', 'in_reply_to_status_id' => 123456));
    $status = $connection->delete('statuses/destroy/12345');

Contributors
============

* [Abraham Williams](https://gnusocial.com/abraham) - Main developer, current maintainer.