u-alberta/uoda-client

There is no license information available for the latest version (3.0.11) of this package.

A PHP client to interface with the UAlberta Open Data API (UODA)

3.0.11 2019-01-03 20:04 UTC

README

Build Status Coverage Status

Note: This library is currently under development, and unannounced BC-breaking changes may occur at any point.

Installing

The current only supported method for installing the client is with Composer. You should be able to use the classes fine with other autoloaders and dependency managers, but you're on your own with those.

composer require u-alberta/uoda-client

Configuration

Laravel Integration

The package optionally integrates with the Laravel Framework - of course you can use it without Laravel, but internally we use Laravel so the integration is convenient for us. Simply composer require the package into your Laravel installation, and add this to your service providers array in config/app.php:

UAlberta\IST\UODA\Client\FrameworkIntegration\Laravel\UODAClientServiceProvider::class

To publish the configuration run:

php artisan vendor:publish

Now you can edit any of the values in config/uoda-client.php to suit your needs.

Instantiating the configuration object (which you will need to use the UODA Client) can be done by calling

$configuration = App::make(\UAlberta\IST\UODA\Client\Configuration::class);

Without Laravel

Whenever you use the UODA client, you'll need to inject a Configuration instance into the client. A Configuration object can be instantiated by

$configuration = new \UAlberta\IST\UODA\Client\Configuration([
    'oauth_server_url' => "OAUTH_SERVER_HERE",
    'api_server_url' => "API_SERVER_HERE",
    'client_id' => "YOUR_CLIENT_ID",
    'client_secret' => "YOUR_CLIENT_SECRET",
    'redirect_uri' => "YOUR_CLIENT_REDIRECT",
    'grant_type' => "OPTIONAL - 'authorization_code' or 'client_credentials'",
    'scopes' => [ // OPTIONAL - defaults to just 'basic'
        'scopes',
        'you',
        'want'
    ]
]);

Authentication

The client makes authentication to the OAuth server a breeze. An OAuth access token is required for every call to the API, so this step is required.

To start you have to instantiate a new Authenticator instance - you'll need to inject a Configuration as described above

$authenticator = new UAlberta\IST\UODA\Client\Authentication\Authenticator($configuration)

If using Laravel, we recommend taking advantage of the IoC container, and injecting the Authenticator into your controller as such:

class AuthenticationController {
    protected $authenticator;
    public function __construct(UAlberta\IST\UODA\Client\Authentication\Authenticator $authenticator) {
        $this->authenticator = $authenticator;
    }
}

Start the flow by redirecting the user to the result of:

$redirect_url = $authenticator->beginOAuth();

The user will then be sent to the OAuth server to complete the flow. The next time they hit your server will be at the redirect_uri you passed in the Configuration option.

try {
    $token = $authenticator->processEndpointResponse()
} catch (UAlberta\IST\UODA\Client\NotAuthorizedException $exception) {
    // Thrown if the client chooses to deny authorization
    $exception->get() //Returns an instance of UAlberta\IST\UODA\Client\Data\Error containing error information
} catch (UAlberta\IST\UODA\Client\ClientException $exception) {
    // Other errors that might occur during the flow
    $exception->get() //Returns an instance of UAlberta\IST\UODA\Client\Data\Error containing error information
}

Since NotAuthorizedException inherits from ClientException, if you wish to specifically catch the case where the user has willfully denied authorization it must be first in the exception handling chain.

A successful process will yield a UODAToken into your $token variable. If you had the user.identification scope enabled, then there will be a resourceOwnerId property which you can get, that will be the user's person_id at the institution. Without that scope, resourceOwnerId will be null, however there will alwasy be a ccid property that you can access to verify who just logged in.

$client = new UAlberta\IST\UODA\Client\Client($token, $configuration);
$user = $client->get('me'); // Returns an instance of UAlberta\IST\UODA\Client\Data\User

Assuming everything went well, you can now query successfully using your new token! Remember to store the access_token you've received back if you wish to make API calls.