Weave Code
Laravel Xero Oauth2 Laravel Package
webfox/laravel-xero-oauth2
A Laravel package for integrating Xero OAuth2 authentication. It streamlines the authorization flow, token storage and refresh, and authenticated Xero API requests, making it easier to connect Laravel applications to Xero.
A Laravel integration for Xero using the Oauth 2.0 spec
Frequently asked questions about Laravel Xero Oauth2
- How do I install webfox/laravel-xero-oauth2 in a Laravel application?
- Install it with Composer using composer require webfox/laravel-xero-oauth2, then publish the package config and run the migration that creates the token table. You will need to create a Xero app in the Xero developer portal and put the client ID, client secret, and redirect URI into your .env file. After that, hit the package's authorization route to walk through the Xero consent screen. Expect the whole setup to be a one-to-two day spike including the surrounding wiring.
- Which Laravel and PHP versions does this package support?
- The package is a thin adapter over the official xeroapi/xero-php-oauth2 SDK and league/oauth2-client, so its real support matrix is whatever Illuminate and PHP constraints appear in its composer.json. That matrix is unverified against current Laravel 10, 11, and 12 releases and PHP 8.2 or 8.3, so treat it as a hard gate before adoption. Check the composer.json constraints and run a throwaway install on your exact framework and PHP versions before committing.
- How are Xero OAuth2 tokens stored and refreshed with this package?
- The package ships a migration for a token table and persists access and refresh tokens there, then uses them when bootstrapping the Xero SDK client. Xero access tokens expire in roughly 30 minutes and refresh tokens rotate on every use, so the stored refresh token must be updated each time. The package handles the refresh call, but it does not guarantee locking around it. Whether storage is a single row, per-tenant rows, or a polymorphic relation to your own tenant model depends on the implementation, so read the migration and repository code before designing around it.
- How do I make authenticated Xero API calls, such as fetching invoices or contacts?
- Resolve the package facade or the underlying SDK client from the container and use the Xero Accounting API to reach contacts, invoices, or bank transactions. Most calls require the Xero tenant or connection ID, so you will need a way to map your application's tenant to the stored Xero connection. The package does not model accounting domain logic, so mapping responses into your own models is entirely your code. That division is intentional: treat the package as infrastructure plumbing, not a domain abstraction.
- Can I use this package in a multi-tenant Laravel SaaS?
- Yes, but only if you own the tenancy layer yourself. The package exposes a config file, token table, OAuth callback route, and facade, and leaves per-tenant token scoping to you. For a single-tenant or few-tenant back-office app it is proportionate; for a multi-tenant SaaS where every customer connects their own Xero organisation, you need your own connection model and a reliable way to select the right tenant per request or job. Incremental authorisation, where scopes are added to a live connection later, is also something you should verify rather than assume.
- Does the package prevent concurrent token refresh races in queued jobs?
- No. This is the highest-severity failure mode with Xero OAuth2 and the package will not solve it for you. Because refresh tokens rotate on use, two workers refreshing the same tenant's token at the same time can invalidate that tenant's connection and force a re-consent. Use Laravel's atomic locks or a cache mutex around refresh, or funnel all refreshes through a single scheduled job, and make your failure path re-authorise gracefully.
- Does webfox/laravel-xero-oauth2 support Xero webhooks and signature verification?
- The package's stated scope is the OAuth2 authorization flow, token storage and refresh, and authenticated API requests, so webhook receiving is not its focus. If you need webhooks you will likely build the endpoint yourself, verifying the HMAC-SHA256 signature over the raw request body and responding quickly while fetching the changed resources asynchronously. You will also need to register the intent-to-receive on the connection. Confirm against the repo before assuming any of this exists.
- Does the package handle Xero API rate limits and retries?
- Rate-limit handling is effectively yours. The package bootstraps the SDK and gets out of the way, so any retry or backoff strategy around 429 responses and the daily/minute limit headers has to live in your job and HTTP layers. Design your sync as queued jobs with exponential backoff and idempotent writes rather than expecting the package to absorb throttling for you.
- Is webfox/laravel-xero-oauth2 safe to depend on in production?
- It is usable, but the risk profile is a single-agency maintainer (Webfox) with modest adoption at around 59 GitHub stars and one recent release date, which is weak evidence of sustained maintenance. There is no SLA and no public support commitment, so treat it as likely adequate but under-exercised, meaning edge cases surface in your environment rather than in other people's issue reports. If the Xero integration becomes business-critical, plan to vendor or fork the package so you control the Laravel and SDK version constraints.
- Why use this package instead of the xeroapi/xero-php-oauth2 SDK directly?
- The package is a thin Laravel adapter that wraps the official Xero SDK and league/oauth2-client, adding a service provider, a config file, a token migration, an OAuth callback route, and a facade. If you are on a Laravel monolith that already uses providers, facades, queues, and Eloquent, that saves you wiring the consent flow, token persistence, and SDK bootstrapping yourself. If you run a non-Laravel runtime or a DDD codebase that resists facades, or you want a dedicated connector service boundary, using the SDK directly or via Laravel Socialite is often cleaner. Either way, verify which xeroapi SDK major version is pinned so you do not inherit version lag.
Weaver
How can I help you explore Laravel packages today?