evance/apiclient

Client library for Evance APIs

dev-master 2021-07-21 10:30 UTC

This package is not auto-updated.

Last update: 2024-03-15 13:30:44 UTC


README

A PHP client library for accessing Evance APIs

Work in progress!

This library is currently a work in progress. It is therefore subject to dramatic changes.

Requirements

PHP 5.6 or higher

Installation

You can use Composer (our preferred method) or download the source.

Composer

Once you have installed composer, execute the following command in your project root to install this library:

composer require evance/apiclient

You should ensure you have included the autoloader for your project:

require_once '/path/to/your-project/vendor/autoload.php';

Download

At the moment we do not have a release complete with its dependencies - it'll be coming soon.

Examples

Authentication with OAuth 2.0

This method is for Web Clients requiring user authorisation. Follow the steps below to obtain an access token from Evance.

  1. Create your App and credentials.

  2. Download the JSON credentials and save them into a configuration directory within you project.

  3. Set the path to your credentials as below:

    use Evance\ApiClient;
    $client = new ApiClient();
    $client->loadAuthConfig('/path/to/client-credentials.json');
  4. Set the scopes required for the API you are going to call.

    $client->addScope('shipping');
  5. Set your application's redirect URI. The redirect URI must match the authorised redirect URI you set when creating your client credentials.

    $client->setRedirectUri('https://example.com/callback');
  6. Set a use-once state number. This number will be returned to your callback page so that you may confirm you sent the original request. Therefore, you will need to ensure you can persist the number to the callback page. This may done, for example, within a session variable.

    $client->setState($nonce);
  7. Get the Evance OAuth 2.0 URL for a user to authorise access. You can either use this URL in redirect or provide a link for the user to click.

    $url = $client->createAuthorizeUrl();
  8. In the callback script (your redirect URI), you will need to exchange the authorisation code for an access token. You should also verify that state is as expected.

    $token = $client->authenticate($_GET);

Authenticating Server-to-server clients

This method is for obtaining single use access tokens. Unlike Web Clients a Server Key does not have a refresh token so a new access token must be obtained every time a token expires.

  1. Create your App and credentials.

  2. Download the JSON credentials and save them into a configuration directory within you project.

  3. Set the path to your credentials as below:

    use Evance\ApiClient;
    $client = new ApiClient();
    $client->loadAuthConfig('/path/to/server-credentials.json');
  4. Optionally, you may set the scope you wish to grant the access token. Omitting this step will grant the access token full access to the scopes granted to your App.

    $client->addScope('shipping');
  5. Now you can obtain the access token from Evance.

    $token = $client->fetchAccessTokenWithJwt();