‘XeroOAuth-PHP’ tutorial


Here is a small tutorial to help anyone trying to use ‘XeroOAuth-PHP’ sample code.

Note: There is no specific hardware or operating system requirements to create and run a PHP app using the PHP wrapper, however these instructions are based on using Mac and MAMP as webserver

Although the instructions could change a bit for Windows installation, the overall process will still remain the same.


Prerequisites

These remain common irrespective of the OS or application or sample code used.

Xero Account

You should have an account signed up with Xero (if not, you can signup for a trial account here).

Xero Organisation

You should have a Xero Organisation to authorise your integration/application. You can either add a trial organisation (details here) or access Demo Company (details here).

Applications

Once you have Xero account and Organisation sorted, go to app.xero.com to create an application. Depending on the purpose and usage of your integration you can choose to create application of type Public, Private or Partner. Each is set up differently and details are on their relevant pages.

Key’s and Certificates

Depending on the type of application you choose to create on app.xero.com, you should have the application keys:(consumer key and consumer/shared secret) and the public/private key pair (namely ‘publickey.cer’ and ‘privatekey.pem’). You can create public/private key pair yourself (details here). Last but not least, if you are a technology partner with Xero and using a Partner application, Xero API team will provide you with an Entrust SSL certificate that you would need to present while accessing partner API URL’s.

Installing and using the PHP Wrapper

Please make sure you have all the prerequisites (mentioned above) before proceeding further:

These instructions allow the ‘XeroOAuth-PHP’ SDK to work with MAMP on your local system for the purpose of this demonstration.

Downloading the SDK and installing MAMP

1) Go to the Developer Center SDK header and click PHP

2) Download the ‘XeroOAuth-PHP’ sample code Zip file from Github

3) Install MAMP on your local system

NOTE: Make sure to check the port configuration part on MAMP console (it usually defaults to either 80 or 8888 but in case, on your local system, these ports are already being used by other services, you may have to change it to available ports for MAMP services to run. You can refer MAMP support documentation for this here)

4) Extract the sample code zip file ‘XeroOAuth-PHP-master.zip’ and transfer the unzipped file ‘XeroOAuth-PHP-master’ to ‘htdocs’ folder inside your MAMP install directory.

5) Start editing the necessary files

Configuring and connecting the app

The credentials required to connect an app depends on what app type you're using. Here are instructions for connecting the two most common app types - Public and Private.

Public application

If you have created a Public application on app.xero.com, as per prerequisites you will have the application keys(consumer key and consumer/shared secret).
  1. Go to your MAMP install directory and navigate to (htdocs > XeroOAuth-PHP-master > public.php).
  2. Open the ‘public.php’ file in a text editor and start to fill in your consumer_key and shared_secret values along with an identifying ‘$useragent’ parameter (such as the name of your app). Public apps use the HMAC-SHA1 signing method and will not require public/private key pair.
  3. Fill in the ‘OAUTH_CALLBACK’ parameter. If you're running the application code on MAMP (hosted locally on local machine/host) you can leave the OAuth_callback to be the same else populate with appropriate domain name. For more information on callback domains please refer to our documentation here.
  4. Navigate to localhost ( http://localhost:portnumber) which should show you the ‘XeroOAuth-PHP-master’ and once you click on it it will display the files in the directory, including the Public, Private and Partner php files. For this part, select public.php.
  5. Click Authenticate and login with your Xero account (used to create the public application above).
  6. Choose the organisation you want to connect to from the list of organisations. You'll only see organisatoins that you have Standard or Adviser level rights for.
  7. Post authorisation it will redirect back to your application (hosted locally) and provides with options to do run various tests.
  8. Add or modify tests on the test.php file, and edit the links to the test by editing the testrunner.php file.

Private application:

If you have created a Private application on app.xero.com, as per prerequisites you will have the application keys (consumer key and consumer/shared secret) and public/private key pair.

  1. Go to your MAMP install directory and navigate to htdocs > XeroOAuth-PHP-master > private.php.
  2. Open this ‘private.php’ file in a text editor and start to fill in your consumer_key and shared_secret values along with an identifying ‘$useragent’ parameter (such as the name of your app). Since private applications are organisation specific, you won’t have to provide ‘oauth_callback’ as the authorisation of the application against Organisation would have already been completed while creating private application.
  3. Private applications use the RSA-SHA1 signing method and will require public/private key pair. Put the privatekey.pem & publickey.cer you generated into ‘certs’ folder (under MAMP install directory > XeroOAuth-PHP-master > certs).
  4. Navigate to localhost ( http://localhost:portnumber) which should show you the ‘XeroOAuth-PHP-master’ and once you click on it it will display the files in the directory, including the Public, Private and Partner php files. For this part, select private.php.
  5. You'll be taken to private.php page which displays links to various tests. Add or modify the tests on the test.php file, and edit the links to the test by editing the testrunner.php file.


Working with the PHP SDK Demo

A demonstration of installing and working with the PHP SDK and the API.