Download the PHP package consilience/xero-api-client without Composer

Xero API Client

Table of Contents

• Xero API Client
• Table of Contents
  • Simple Usage - Partner Application
    • Token Persistence
    • Authorising an Application
      • Factories
    • Accessing the Xero API.
      • Create OAuth1 Token Object
  • Configure HTTP Client
  • TODO

API package for Xero authenticated access. Leverages PSR-7, PSR-17 and PSR-18.

Handles the OAuth 1.0a requests, and token renewals for the partner application. It does this by offering a decorated PSR-18 client.

Provides support for the authentication flow to capture the OAuth 1.0a tokens.

Features include:

• Support for Partner Application only at present. (Note: support for Private Applications is being added and will be tidied up soon.
• Automatic token renewal of a token by its local age, or on an expiry flagged by the remote Xero API.
• Hook to the application for persistence of the OAuth1 token credentails when they get renewed. This keeps the burden of renewals away from the application.

Simple Usage - Partner Application

Token Persistence

The Xero Partner tokens expire every 30 minutes and need to be renewed. The renewed tokens then must be saved for use on the next API call. To perform the persistence in the examples below, we will invoke the imaginary class TokenStorage. It will have methods:

TokenStorage::get($tokenKey): string;
TokenStorage::save($tokenKey, string $tokenDetails);

The token details will be an array encoded to a JSON string.

The $token key just identifies a token amoung many in storage. We'll just use 123 as our key.

Authorising an Application

This stage is to allow a user to authorise the application to access their Xero organisation. The result will be a set of token credentials (Access Token) that can be used to access the API.

You can use an alternative package for obtaining authorisation, such as Guzzle and Invoiced/oauth1-xero. Or use this package to reduce dependencies, whatever fits your needs best.

There are a couple of steps in the OAuth 1.0a flow to get the tokens:

1. Get a temporary token.
2. Send the user to Xero to authorise the applicarion.
3. The user returns with a verification key (a CSRF token).
4. Use the temporary token and the verification key to exchange for the long-term Access Token.

Here are the details. For each stage you will need the authorisation client:

First get a temporary token from Xero:

Then use the temporary token to redirect the user to Xero:

The user will come back to the callback URL with a verifier:

Now the access token can be stored for using to access the Xero API. We will store it against token key 123 so we can get it back later.

Factories

The Authorise client needs a few additional objects to operate:

• A PSR-17 HTTP factory (to generate Reqeusts and URIs).
• A PSR-18 client that it decorates.

These can be installed from Guzzle:

composer require http-interop/http-factory-guzzle

or use diactoros:

composer require http-interop/http-factory-diactoros

Any other PSR-17 HTTP URI and Request factory, and PSR-18 client can be used.

Alternatively, you can enable auto-discovery and leave the Authorise client to discover the installed factories and create a client for itself.

composer require http-interop/http-factory-discovery
composer require php-http/guzzle6-adapter

Accessing the Xero API.

Create OAuth1 Token Object

To access the API, start by creating an OAuth 1.0a token object.

For the Partner Application this will be a renewable token that will be updated in storage each time it gets renewed.

For the Private Application the oauth token is a lot simpler. Set the token to the consumer key you were given when setting up the private application.

Configure HTTP Client

Now we set up a Partner or Private application client.

The application should be provided, which is used as a User Agent. This helps Xero when they look at their logs.

$app = $app->withApplicationName('My Ace Application');

To support Guzzle as the underlying PSR-18 client, and the unserlying PSR-17 message factory through auto-discovery, you will need to install the adapters through composer:

• guzzlehttp/psr7
• guzzlehttp/guzzle
• php-http/guzzle6-adapter
• http-interop/http-factory-guzzle [needed for the php-http/guzzle6-adapter adaper to work, no idea why]
• http-interop/http-factory-discovery [later]

Otherwise, the message factory and client can be passed in when instantiating.

Now we can make a request of the API. Any request wil work - GET, POST, PUT and to any Xero endpoint that your application supports.

That's it. With the correct method, URL, Accept header and payload (if using POST) you can send requests to all parts of the Xero API. Token renewals - for the Partner application at least - will be handled for you automatically and invisibly to the application.

Another package will handle the payload parsing and request building. This package is just concerned with the HTTP access with OAuth 1.0a credentials. The Xero API Operations package is in development (and usable now) here: https://github.com/consilience/xero-api-sdk

TODO

• Tests (as usual).
• Is there a better way of handling key files, perhaps as streams, so it can be supplied as a path, a string, a file resource etc?
• Some better exception handling, so we can catch a failed token, redacted authorisation, general network error etc and handle appropriately.