Download the PHP package calcinai/xero-php without Composer
On this page you can find all versions of the php package calcinai/xero-php. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download calcinai/xero-php
More information about calcinai/xero-php
Files in calcinai/xero-php
Package xero-php
Short Description A client implementation of the Xero API, with a cleaner OAuth interface and ORM-like abstraction.
License MIT
Homepage https://github.com/calcinai/xero-php
Informations about the package xero-php
XeroPHP
A client library for the Xero API, wrapping Guzzle and ORM-like models.
This library was developed for the traditional Private, Public and Partner applications, but is now based on OAuth 2 scopes.
Requirements
- PHP 5.6+
Setup
Using composer:
Migration from 1.x/OAuth 1a
There is now only one flow for all applications, which is most similar to the legacy Public application. All applications now require the OAuth 2 authorisation flow and specific organisations to be authorised at runtime, rather than creating certificates during app creation.
As there is now only one type of application, you now create a generic XeroPHP\Application
with your access token and tenantId, from this
point onward, all your code should remain the same.
Usage
Before resource requests can be made, the application must be authorised. The authorisation flow will give you an access token and a
refresh token. The access token can be used to retrieve a list of tenants (Xero organisations) which the app is authorised to query, then,
in conjunction with the desired tenantId, you can instantiate a XeroPHP\Application
to query the API relating to a specific organisation.
For applications that require long-lived access to organisations, the refresh flow will need to be built in to catch and expired access token and refresh it.
Authorization Code Flow
Usage is the same as The League's OAuth client, using \Calcinai\OAuth2\Client\Provider\Xero
as the provider.
You can then store the token and use it to make requests against the api to the desired tenants
Scopes
OAuth scopes, indicating which parts of the Xero organisation you'd like your app to be able to access. The complete list of scopes can be found here.
Refreshing a token
Client credentials flow (custom connections)
You can utilise the client credentials grant type by creating a "Custom Connection". Once you have your client credentials, usage is the same as The League's OAuth client. You can select your scopes when configuring your Custom Connection.
Interacting with the API
Once you've got a valid access token and tenantId, you can instantiate a XeroPHP\Application
. All the examples below refer to models
in the XeroPHP\Models\Accounting
namespace. Additionally, there are models for PayrollAU
, PayrollUS
, Files
, and Assets
.
Refer to the examples for more complex usage and nested/related objects.
Instantiate an Application
Create a XeroPHP instance (sample config included):
Load a collection
Load a collection with pagination
Load collection of objects, for a single page, and loop through them (Why?)
Load a collection with WHERE filtering
Search for objects meeting certain criteria
Load a specific resource
Load resources by their GUID
Create a new resource
Populate resource parameters with their setters
Saving resources
If you have created a number of objects of the same type, you can save them all in a batch by passing an array to .
From v1.2.0+, Xero context can be injected directly when creating the objects themselves, which then exposes the method. This is necessary for the objects to maintain state with their relations.
Saving related models
If you are saving several models at once, by default additional model attributes are not updated. This means if you are saving an invoice with a new contact, the contacts ContactID
is not updated. If you want the related models attributes to be updated you can pass a boolean flag with true
to the save method.
Attachments
To set the IncludeOnline
flag on the attachment, pass true
as the second parameter for ->addAttachment()
.
PDFs
Models that support PDF export will inherit a method, which returns the raw content of the PDF. Currently this is limited to Invoices and CreditNotes.
Unit price precision
The unit price decimal place precision (the unitdp
parameter) is set via a config option:
Practice Manager
If requiring the "practicemanager" scope please query models using the following syntax
Webhooks
If you are receiving webhooks from Xero there is Webhook
class that can help with handling the request and parsing the associated event list.
Validating Webhooks
To ensure the webhooks are coming from Xero you must validate the incoming request header that Xero provides.
Handling Errors
Your request to Xero may cause an error which you will want to handle. You might run into errors such as:
HTTP 400 Bad Request
by sending invalid data, like a malformed email address.HTTP 429 Too Many Requests
by hitting the API to quickly in a short period of time.HTTP 503 Rate Limit Exceeded
by hitting the API to quickly in a short period of time.HTTP 400 Bad Request
by requesting a resource that does not exist.
These are just a couple of examples and you should read the official documentation to find out more about the possible errors.
Rate Limit Exceptions
Xero returns header values indicating the number of calls remaining before reaching their API lmits. https://developer.xero.com/documentation/guides/oauth2/limits/
The Application is updated following every request and you can track the number of requests remaining using the Application::getAppRateLimits() method. It returns an array with the following keys and associated integer values.
'last-api-call' // The int timestamp of the last request made to the Xero API
'app-min-limit-remaining' // The number of requests remaining for the application as a whole in the current minute. The normal limit is 10,000.
'tenant-day-limit-remaining' // The number of requests remaining for the individual tenant by the day, limit is 5,000.
'tenant-min-limit-remaining' // The number of requests remaining for the individual tenant by the minute, limit is 60.
These values can be used to decide if additional requests will throttled or sent to some message queue. For example:
If the Application exceeds the rate limits Xero will return an HTTP 429 Too Many Requests response. By default, this response is caught and thrown as a RateLimitException.
You can provide a more graceful method of dealing with HTTP 429 responses by using the Guzzle RetryMiddleware. You need to replace the transport client created when instantiating the Application. For example:
Thrown Exceptions
This library will parse the response Xero returns and throw an exception when it hits one of these errors. Below is a table showing the response code and corresponding exception that is thrown:
HTTP Code | Exception |
---|---|
400 Bad Request | \XeroPHP\Remote\Exception\BadRequestException |
401 Unauthorized | \XeroPHP\Remote\Exception\UnauthorizedException |
403 Forbidden | \XeroPHP\Remote\Exception\ForbiddenException |
403 ReportPermissionMissingException | \XeroPHP\Remote\Exception\ReportPermissionMissingException |
404 Not Found | \XeroPHP\Remote\Exception\NotFoundException |
429 Too Many Requests | \XeroPHP\Remote\Exception\RateLimitExceededException |
500 Internal Error | \XeroPHP\Remote\Exception\InternalErrorException |
501 Not Implemented | \XeroPHP\Remote\Exception\NotImplementedException |
503 Rate Limit Exceeded | \XeroPHP\Remote\Exception\RateLimitExceededException |
503 Not Available | \XeroPHP\Remote\Exception\NotAvailableException |
503 Organisation offline | \XeroPHP\Remote\Exception\OrganisationOfflineException |
See: Response codes and errors documentation
Handling Exceptions
To catch and handle these exceptions you can wrap the request in a try / catch block and deal with each exception as needed.
All versions of xero-php with dependencies
calcinai/oauth2-xero Version ^1.0
guzzlehttp/guzzle Version ^6.5|^7.0
guzzlehttp/psr7 Version ^1.5|^1.6|^2.1.1
ext-json Version *
ext-simplexml Version *