global-exam/api-sdk-php

GlobalExam API PHP SDK

This package's canonical repository appears to be gone and the package has been frozen as a result.

Maintainers

Details

github.com/global-exam/api-sdk-php

Homepage

Source

Issues

Installs: 4 294

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 3

Forks: 0

Open Issues: 0

dev-master 2020-03-18 13:37 UTC

Requires

Requires (Dev)

MIT 79ae417ab535d7b6b91c1418a0fe5c02f0cfcd76

This package is not auto-updated.

Last update: 2022-06-23 01:47:06 UTC

README

Build Status StyleCI

Requirements

  • PHP >= 5.6
  • cURL library enabled

Install

Composer

composer require global-exam/api-sdk-php:dev-master

Usage

As a guest

use GlobalExam\Api\Sdk\Api;

$api = new Api();

As a guest who needs a token

use GlobalExam\Api\Sdk\Api;
use GlobalExam\Api\Sdk\Authentication\OAuthClient;
use GlobalExam\Api\Sdk\Authentication\PasswordCredentialsGrant;

$oauthClient   = new OAuthClient('clientId', 'clientSecret');
$authenticator = new PasswordCredentialsGrant($oauthClient, 'email@domain.com', 'password', '', [
    'Accept-Language' => 'fr',
    'X-Subdomain'     => 'your-organization-subdomain',
    'X-Agent-Country' => 'fr',
    'X-Forwarded-For' => '0.0.0.0',
]);

$api = new Api($authenticator);

// Keep tokens for future calls
$tokens = $api->login();

As a known user

use GlobalExam\Api\Sdk\Api;
use GlobalExam\Api\Sdk\Authentication\AuthorizationCodeGrant;

$tokens = json_decode($tokens->getBody()->getContents(), true);

// Play authenticated calls
$authenticator = new AuthorizationCodeGrant($oauthClient, $tokens, '', [
    'Accept-Language' => 'fr',
    'X-Subdomain'     => 'your-organization-subdomain',
    'X-Agent-Country' => 'fr',
    'X-Forwarded-For' => '0.0.0.0',
]);
$api           = new Api($authenticator);
$api->login();

$response = $api->user()->me(); // ResponseInterface

As a server

use GlobalExam\Api\Sdk\Api;
use GlobalExam\Api\Sdk\Authentication\ClientCredentialsGrant;

$oauthClient   = new OAuthClient('clientId', 'clientSecret');
$authenticator = new ClientCredentialsGrant($oauthClient);

$api    = new Api($authenticator);
$tokens = $api->login();
$tokens = json_decode($tokens->getBody()->getContents(), true);

$api->setAuthenticator(new AuthorizationCodeGrant($oauthClient, $tokens));

Deal with token expiration

You may receive a 401 Unauthorized response from a Guzzle exception.

Try to get another access token based on the current credentials.

try {
    $api->user()->me();
} catch (\GuzzleHttp\Exception\ClientException $e) {
    // Expired token
    if ($e->getResponse()->getStatusCode() === 401) {
        // Ask new credentials based on the current refresh token
        $tokens = $api->user()->oauth()->renewToken();
        $tokens = json_decode($tokens->getBody()->getContents(), true);
        
        // Set a fresh authenticator
        $api->setAuthenticator(new AuthorizationCodeGrant($oauthClient, $tokens, '', [
            'Accept-Language' => 'fr',
            'X-Subdomain'     => 'your-organization-subdomain',
            'X-Agent-Country' => 'fr',
            'X-Forwarded-For' => '0.0.0.0',
        ]);
        
        $response = $api->user()->me();
        $response->getStatusCode(); // 200
    }
}

API Reference

constructor

Description

Creates a new Api instance.

Api ( AuthenticationInterface $authenticator = null ): Api

Input

authenticator

A valid authenticator.

Output

Returns the Api instance.

Example

$oauthClient   = new OAuthClient('clientId', 'clientSecret');
$authenticator = new PasswordCredentialsGrant($oauthClient, 'email@domain.com', 'password', '', [
    'Accept-Language' => 'fr',
    'X-Subdomain'     => 'your-organization-subdomain',
    'X-Agent-Country' => 'fr',
    'X-Forwarded-For' => '0.0.0.0',
]);

$api = new Api($authenticator);

setBaseUrl

Description

Sets another base URL.

setBaseUrl ( string $baseUrl ): Api

Input

baseUrl

A valid URL.

Output

Returns the Api instance.

Example

$api = new Api();
$api->setBaseUrl('http://api.global-exam.io');

setAuthenticator

Description

Set another authenticator.

setAuthenticator ( AuthenticationInterface $authenticator ): Api

Input

authenticator

Any class that implements AuthenticationInterface. Prebuilt classes are:

  • PasswordCredentialsGrant
  • AuthorizationCodeGrant
  • ClientCredentialsGrant

Output

Returns the Api instance.

Example

$api = new Api();

$oauthClient   = new OAuthClient('clientId', 'clientSecret');
$authenticator = new PasswordCredentialsGrant($oauthClient, 'email@domain.com', 'password', '', [
    'Accept-Language' => 'fr',
    'X-Subdomain'     => 'your-organization-subdomain',
    'X-Agent-Country' => 'fr',
    'X-Forwarded-For' => '0.0.0.0',
]);

$api->setAuthenticator($authenticator);

login

Description

Indicates you want to be authenticated.

This will login the user and returns the credentials if you have specified the OAuthPasswordGrant authenticator.

login ( ): Api

Output

Returns the credentials as a ResponseInterface if the OAuthPasswordGrant authenticator is used. Otherwise it returns the current Api instance.

Example

$oauthClient   = new OAuthClient('clientId', 'clientSecret');
$authenticator = new PasswordCredentialsGrant($oauthClient, 'email@domain.com', 'password', '', [
    'Accept-Language' => 'fr',
    'X-Subdomain'     => 'your-organization-subdomain',
    'X-Agent-Country' => 'fr',
    'X-Forwarded-For' => '0.0.0.0',
]);
$api           = new Api($authenticator);

// Keep credentials for future calls
$tokens = $api->login();

// Or

$oauthClient   = new OAuthClient('clientId', 'clientSecret');
$authenticator = new AuthorizationCodeGrant($oauthClient, $tokens, '', [
    'Accept-Language' => 'fr',
    'X-Subdomain'     => 'your-organization-subdomain',
    'X-Agent-Country' => 'fr',
    'X-Forwarded-For' => '0.0.0.0',
]);
$api           = new Api($authenticator);

$api->login();

logout

Description

Disables the authentication for future calls. This will not logout the current user. See User resource.

logout ( $clearCredentials = false ): Api

Input

clearCredentials

If true this will also clear the current authenticator.

Output

Returns the Api instance.

Example

$oauthClient   = new OAuthClient('clientId', 'clientSecret');
$authenticator = new AuthorizationCodeGrant($oauthClient, $tokens, '', [
    'Accept-Language' => 'fr',
    'X-Subdomain'     => 'your-organization-subdomain',
    'X-Agent-Country' => 'fr',
    'X-Forwarded-For' => '0.0.0.0',
]);
$api           = new Api($authenticator);

$api->login();

// Perform actions

$api->logout(true);

clearCredentials

Description

Clear the current authenticator.

clearCredentials ( ): Api

Output

Returns the Api instance.

Example

$oauthClient   = new OAuthClient('clientId', 'clientSecret');
$authenticator = new AuthorizationCodeGrant($oauthClient, $tokens, '', [
    'Accept-Language' => 'fr',
    'X-Subdomain'     => 'your-organization-subdomain',
    'X-Agent-Country' => 'fr',
    'X-Forwarded-For' => '0.0.0.0',
]);
$api           = new Api($authenticator);

$api->login();

// Perform actions

$api->logout();
$api->clearCredentials();

isAuthenticated

Description

To know either you are authenticated or not.

isAuthenticated ( ): bool

Output

Returns true or false.

Example

$oauthClient   = new OAuthClient('clientId', 'clientSecret');
$authenticator = new AuthorizationCodeGrant($oauthClient, $tokens, '', [
    'Accept-Language' => 'fr',
    'X-Subdomain'     => 'your-organization-subdomain',
    'X-Agent-Country' => 'fr',
    'X-Forwarded-For' => '0.0.0.0',
]);
$api           = new Api($authenticator);

$api->login();

$api->isAuthenticated(); // true

$api->logout();

$api->isAuthenticated(); // false

send

Description

Performs an HTTP request to the API.

Most of time, you won't use this method because there are public methods to access to a given resource.

send ( string $method, string $uri, array $body = [], array $params = [], array $headers = [] ): ResponseInterface

Input

method

HTTP verb such as GET, POST, etc.

uri

Path to the resource that will be added to the base URL.

body

Any array that will be JSON-encoded and attached to the request.

params

Any array that will converted to a query string and be added to the URI.

headers

Additional headers.

Output

Returns a response that implements the PSR-7 ResponseInterface interface.

Example

$oauthClient   = new OAuthClient('clientId', 'clientSecret');
$authenticator = new AuthorizationCodeGrant($oauthClient, [
    'access_token'  => 'a',
    'refresh_token' => 'b',
    'expires_in'    => 1,
], '', [
    'Accept-Language' => 'fr',
    'X-Subdomain'     => 'your-organization-subdomain',
    'X-Agent-Country' => 'fr',
    'X-Forwarded-For' => '0.0.0.0',
]);
$api           = new Api($authenticator);
        
$response = $api->send('GET', '/user/me');

// $response->getStatusCode()
// $response->getBody()->getContents()

Resources

Resources allow you to have a quick response instead of building a request by your own.

Browse the src/Resource folder to see what is available.

Example

$api->user()->me();
$api->auth()->register(array $body);

Tests

On project directory:

  • composer install to retrieve phpunit
  • phpunit to run tests