macsidigital/xero-laravel

This package is abandoned and no longer maintained. The author suggests using the macsidigital/laravel-xero package instead.

Xero Laravel package

1.0.6 2019-06-26 09:10 UTC

This package is auto-updated.

Last update: 2021-04-23 12:36:05 UTC


README

Latest Version on Packagist Build Status Total Downloads

No longer maintained, use https://github.com/MacsiDigital/laravel-xero

A little Laravel package to communicate with Xero.

Installation

You can install the package via composer:

composer require macsidigital/xero-laravel

Configuration file

Publish the configuration file

php artisan vendor:publish --provider="MacsiDigital\Xero\XeroServiceProvider"

This will create a xero/config.php within your config directory. Check the Xero documentation for the relevant values in the config.php file. Ensure that the location of the RSA keys matches.

Usage

Everything has been setup to be similar to Laravel syntax.

We also use a little bit of magic to work with Xero's model names. In Xero there are a few different modules (Accounting, Payroll AU etc.), at the minute we only support a small part of the accounting area, but we have set naming so that additional modules can be added in future.

So to use the conacts in the Accounting module we would use the following syntax.

	$xero = new \MacsiDigital\Xero\Xero;
	$xero->AccountingContact->functionName();

Find all

The find all function returns a Laravel Collection so you can use all the Laravel Collection magic

	$xero = new \MacsiDigital\Xero\Xero;
	$contacts = $xero->AccountingContact->all();

Filtered

The filtered find function returns a Laravel Collection so you can use all the Laravel Collection magic

	$xero = new \MacsiDigital\Xero\Xero;
	$contacts = $xero->AccountingContact->where('Name', '==', 'Test Name')->get();

To only get a single item use the 'first' method

	$xero = new \MacsiDigital\Xero\Xero;
	$contact = $xero->AccountingContact->where('Name', '==', 'Test Name')->first();

Find by ID

Just like Laravel we can use the 'find' method to return a single matched result on the ID

	$xero = new \MacsiDigital\Xero\Xero;
	$contact = $xero->AccountingContact->find('ID_String');

Creating Items

We can create and update records using the save function, below is the full save script for a creation. Please note the functions for adding multi array items, like addresses.

	$contact = $xero->AccountingContact->make([
        'Name' => 'Test Name',
        'FirstName' => 'First Name',
        'LastName' => 'Last Name',
        'EmailAddress' => 'test@test.com',
        'IsCustomer' => true,
    ]);
    $contact->addAddress($xero->AccountingAddress->make([
        'AddressType' => 'POBOX',
        'AddressLine1' => 'Test1',
        'AddressLine2' => 'Test2',
        'AddressLine3' => 'Test3',
        'City' => 'City',
        'PostalCode' => 'Test Code',
        'Country' => 'Test Country',
    ]));
    $contact->save();

Example

Here is an example usage case for querying for a contact, creating if not found and then creating an invoice

	$contact = $xero->AccountingContact->where('name', '==', 'Test Name')->first();
    if($contact == null){
        $contact = $xero->AccountingContact->make([
	        'Name' => 'Test Name',
	        'FirstName' => 'First Name',
	        'LastName' => 'Last Name',
	        'EmailAddress' => 'test@test.com',
	        'IsCustomer' => true,
	    ]);
	    $contact->addAddress($xero->AccountingAddress->make([
	        'AddressType' => 'POBOX',
	        'AddressLine1' => 'Test1',
	        'AddressLine2' => 'Test2',
	        'AddressLine3' => 'Test3',
	        'City' => 'City',
	        'PostalCode' => 'Test Code',
	        'Country' => 'Test Country',
	    ]));
	    $contact->save();
    }
    $invoice = $xero->AccountingInvoice->make([
        'Contact' => $contact,
    ]);
    $invoice->addLineItem($xero->AccountingLineItem->make([
        'Description' => 'Test Description',
        'Quantity' => '1',
        'UnitAmount' => '1234.56',
        'AccountCode' => '200'
    ]));
    $invoice->save();

Resources

At present we have the following resources

  • Account
  • Contacts
  • Invoices
  • Payments
  • PrePayments
  • OverPayments
  • CreditNotes

We plan to add more resources in the future but setting up additional models is straight forward, below is the invoice model setup. If you create any models, then create a pull request and we will add into main repo.

	namespace MacsiDigital\Xero\Models\Accounting;

	use MacsiDigital\Xero\Support\Model;

	class Invoice extends Model
	{
	    const ENDPOINT = 'Invoices';
	    const NODE_NAME = 'Invoice';
	    const KEY_FIELD = 'InvoiceID';

	    protected $methods = ['get', 'post', 'put'];

	    protected $attributes = [
	    	'Type' => 'ACCREC',
	        'Contact' => '',
	        'LineItems' => [],
	        'Date' => '',
	        'DueDate' => '',
	        'LineAmountTypes' => '',
	        'InvoiceNumber' => '',
	        'Reference' => '',
	        'BrandingThemeID' => '',
	        'Url' => '',
	        'CurrencyCode' => '',
	        'CurrencyRate' => '',
	        'Status' => '',
	        'SentToContact' => '',
	        'ExpectedPaymentDate' => '',
	        'PlannedPaymentDate' => '',
	        'SubTotal' => '',
	        'TotalTax' => '',
	        'Total' => '',
	        'TotalDiscount' => '',
	        'InvoiceID' => '',
	        'HasAttachments' => '',
	        'Payments' => [],
	        'Prepayments' => [],
	        'Overpayments' => [],
	        'AmountDue' => '',
	        'AmountPaid' => '',
	        'FullyPaidOnDate' => '',
	        'AmountCredited' => '',
	        'UpdatedDateUTC' => '',
	        'CreditNotes' => []
	    ];

	    protected $relationships = [
	        'Contact' => '\MacsiDigital\Xero\Models\Accounting\Contact',
	        'LineItems' => '\MacsiDigital\Xero\Models\Accounting\LineItem',
	        'Payments' => '\MacsiDigital\Xero\Models\Accounting\Payment',
	        'Prepayments' => '\MacsiDigital\Xero\Models\Accounting\Prepayment',
	        'Overpayments' => '\MacsiDigital\Xero\Models\Accounting\Overpayment',
	    ];

	    public function addLineItem($item) 
	    {
	        $this->attributes['LineItems'][] = $item;
	    }
	}

Testing

At present there is no PHP Unit Testing, but we plan to add it in the future, one handy thing to note is on the save function we return a response which will be 'false' if there was a problem, so if you need to trouble shoot then catch this and query it like so

	$response = $contact->save();
    if($response === false){
        dd($response->getContents());
    }

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email colin@macsi.co.uk instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.