kennethsolomon/xero-laravel

💸 使用类似于Eloquent的语法访问Xero会计系统

维护者

详细信息

github.com/kennethsolomon/xero-laravel

源代码

安装: 1

依赖者: 0

建议者: 0

安全: 0

星标: 1

关注者: 0

分支: 40

3.1.2 2022-12-13 05:10 UTC

Requires

LGPL-3.0-only 5a96e9a566cc75e543c3e9ca932b348427e2d99b

  • Kenneth Solomon <mr.kennethsolomon.woop@gmail.com>

phplaravelAccountingeloquentxero

This package is auto-updated.

Last update: 2024-09-14 04:48:24 UTC

README

Xero Laravel 允许开发者使用类似于Eloquent的语法访问Xero会计系统。

请注意，此版本的Xero Laravel 支持Xero OAuth 2.0实现。不再支持使用OAuth 1.x的旧版Xero应用。

StyleCI

安装

您可以使用Composer轻松安装Xero Laravel。只需从项目根目录运行以下命令。

composer require KennethSolomon/xero-laravel

如果您之前从未使用过Composer依赖管理器，请访问Composer网站了解如何开始。

设置

首先，从项目根目录运行以下artisan命令。这将发布包配置文件。

php artisan vendor:publish --provider="KennethSolomon\XeroLaravel\Providers\XeroLaravelServiceProvider"

现在您需要将config/xero-laravel-lf.php文件填充为您的Xero应用（s）的凭据。您可以在Xero账户的我的应用部分创建应用并找到所需的凭据。

如果您只想使用一个Xero应用，标准的配置文件应该足够。您需要做的就是将以下变量添加到您的.env文件中。

XERO_CLIENT_ID=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XERO_CLIENT_SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XERO_REDIRECT_URI=https://example.com/xero-callback

OAuth 2.0流程

为了让用户能够使用您的Xero应用，他们必须首先允许您的应用访问他们的Xero账户。为此，您的Web应用必须执行以下操作。

  1. 将用户重定向到Xero授权URL。
  2. 捕获Xero的响应，并获取访问令牌。
  3. 检索租户列表（通常是Xero组织），并让用户选择一个。
  4. 将访问令牌和选定的租户ID存储在用户的账户中，以供将来使用。
  5. 在使用访问令牌之前，检查其是否已过期，并在必要时刷新它。

以下控制器展示了这些步骤的实际操作。

<?php
use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use KennethSolomon\XeroLaravel\OAuth2;
use League\OAuth2\Client\Token\AccessToken;

class XeroController extends Controller
{
    private function getOAuth2()
    {
        // This will use the 'default' app configuration found in your 'config/xero-laravel-lf.php` file.
        // If you wish to use an alternative app configuration you can specify its key (e.g. `new OAuth2('other_app')`).
        return new OAuth2();
    }

    public function redirectUserToXero()
    {
        // Step 1 - Redirect the user to the Xero authorization URL.
        return $this->getOAuth2()->getAuthorizationRedirect();
    }

    public function handleCallbackFromXero(Request $request)
    {
        // Step 2 - Capture the response from Xero, and obtain an access token.
        $accessToken = $this->getOAuth2()->getAccessTokenFromXeroRequest($request);

        // Step 3 - Retrieve the list of tenants (typically Xero organisations), and let the user select one.
        $tenants = $this->getOAuth2()->getTenants($accessToken);
        $selectedTenant = $tenants[0]; // For example purposes, we're pretending the user selected the first tenant.

        // Step 4 - Store the access token and selected tenant ID against the user's account for future use.
        // You can store these anyway you wish. For this example, we're storing them in the database using Eloquent.
        $user = auth()->user();
        $user->xero_access_token = json_encode($accessToken);
        $user->tenant_id = $selectedTenant->tenantId;
        $user->save();
    }

    public function refreshAccessTokenIfNecessary()
    {
        // Step 5 - Before using the access token, check if it has expired and refresh it if necessary.
        $user = auth()->user();
        $accessToken = new AccessToken(json_decode($user->xero_access_token));

        if ($accessToken->hasExpired()) {
            $accessToken = $this->getOAuth2()->refreshAccessToken($accessToken);

            $user->xero_access_token = $accessToken;
            $user->save();
        }
    }
}

默认情况下，配置文件中定义了有限的权限范围（空格分隔）。您可能需要根据应用程序的预期用途添加权限范围。例如，添加accounting.transactions权限允许您管理发票，添加accounting.contacts.read权限允许您读取联系人信息。

Xero的文档提供了完整的权限范围列表。

用法

要使用Xero Laravel，您首先需要获取用户存储的访问令牌和租户ID。您可以使用这些信息来创建一个新的XeroApp对象，该对象表示您的Xero应用。

use KennethSolomon\XeroLaravel\XeroApp;
use League\OAuth2\Client\Token\AccessToken;

$user = auth()->user();

$xero = new XeroApp(
            new AccessToken(json_decode($user->xero_oauth_2_access_token)),
            $user->xero_tenant_id
        );

然后，您可以使用类似于Eloquent的语法立即访问Xero数据。以下代码片段显示了可用的语法。当API返回多个结果时，它们将作为Laravel Collection返回。

# Retrieve all contacts
$contacts = $xero->contacts()->get();
$contacts = $xero->contacts;

# Retrieve contacts filtered by name
$contacts = $xero->contacts()->where('Name', 'Bank West')->get();

# Retrieve an individual contact filtered by name
$contact = $xero->contacts()->where('Name', 'Bank West')->first();

# Retrieve an individual contact by its GUID
$contact = $xero->contacts()->find('34xxxx6e-7xx5-2xx4-bxx5-6123xxxxea49');

# Retrieve multiple contact by their GUIDS
$contacts = $xero->contacts()->find([
    '34xxxx6e-7xx5-2xx4-bxx5-6123xxxxea49',
    '364xxxx7f-2xx3-7xx3-gxx7-6726xxxxhe76',
]);

可用关系

以下列表显示了所有可用于访问与您的Xero应用相关数据的关系（例如，$xero->relationshipName）。

注意：如果相关的服务（s）未为您的Xero账户启用，则其中一些关系可能不可用。

accounts
addresses
assetsAssetTypeBookDepreciationSettings
assetsAssetTypes
assetsOverviews
assetsSettings
attachments
bankTransactionBankAccounts
bankTransactionLineItems
bankTransactions
bankTransferFromBankAccounts
bankTransferToBankAccounts
bankTransfers
brandingThemes
contactContactPeople
contactGroups
contacts
creditNoteAllocations
creditNotes
currencies
employees
expenseClaimExpenseClaims
expenseClaims
externalLinks
filesAssociations
filesFiles
filesFolders
filesObjects
invoiceLineItems
invoiceReminders
invoices
itemPurchases
itemSales
items
journalJournalLines
journals
linkedTransactions
manualJournalJournalLines
manualJournals
organisationBills
organisationExternalLinks
organisationPaymentTerms
organisationSales
organisations
overpaymentAllocations
overpaymentLineItems
overpayments
payments
payrollAUEmployeeBankAccounts
payrollAUEmployeeHomeAddresses
payrollAUEmployeeLeaveBalances
payrollAUEmployeeOpeningBalances
payrollAUEmployeePayTemplateDeductionLines
payrollAUEmployeePayTemplateEarningsLines
payrollAUEmployeePayTemplateLeaveLines
payrollAUEmployeePayTemplateReimbursementLines
payrollAUEmployeePayTemplateSuperLines
payrollAUEmployeePayTemplates
payrollAUEmployeeSuperMemberships
payrollAUEmployeeTaxDeclarations
payrollAUEmployees
payrollAULeaveApplicationLeavePeriods
payrollAULeaveApplications
payrollAUPayItemDeductionTypes
payrollAUPayItemEarningsRates
payrollAUPayItemLeaveTypes
payrollAUPayItemReimbursementTypes
payrollAUPayItems
payrollAUPayRuns
payrollAUPayrollCalendars
payrollAUPayslipDeductionLines
payrollAUPayslipEarningsLines
payrollAUPayslipLeaveAccrualLines
payrollAUPayslipLeaveEarningsLines
payrollAUPayslipReimbursementLines
payrollAUPayslipSuperannuationLines
payrollAUPayslipTaxLines
payrollAUPayslipTimesheetEarningsLines
payrollAUPayslips
payrollAUSettingAccounts
payrollAUSettingTrackingCategories
payrollAUSettings
payrollAUSuperFundProducts
payrollAUSuperFundSuperFunds
payrollAUSuperFunds
payrollAUTimesheetTimesheetLines
payrollAUTimesheets
payrollUSEmployeeBankAccounts
payrollUSEmployeeHomeAddresses
payrollUSEmployeeMailingAddresses
payrollUSEmployeeOpeningBalances
payrollUSEmployeePayTemplates
payrollUSEmployeePaymentMethods
payrollUSEmployeeSalaryAndWages
payrollUSEmployeeTimeOffBalances
payrollUSEmployeeWorkLocations
payrollUSEmployees
payrollUSPayItemBenefitTypes
payrollUSPayItemDeductionTypes
payrollUSPayItemEarningsTypes
payrollUSPayItemReimbursementTypes
payrollUSPayItemTimeOffTypes
payrollUSPayItems
payrollUSPayRuns
payrollUSPaySchedules
payrollUSPaystubBenefitLines
payrollUSPaystubDeductionLines
payrollUSPaystubEarningsLines
payrollUSPaystubLeaveEarningsLines
payrollUSPaystubReimbursementLines
payrollUSPaystubTimeOffLines
payrollUSPaystubTimesheetEarningsLines
payrollUSPaystubs
payrollUSSalaryandWages
payrollUSSettingAccounts
payrollUSSettingTrackingCategories
payrollUSSettings
payrollUSTimesheetTimesheetLines
payrollUSTimesheets
payrollUSWorkLocations
phones
prepaymentAllocations
prepaymentLineItems
prepayments
purchaseOrderLineItems
purchaseOrders
receiptLineItems
receipts
repeatingInvoiceLineItems
repeatingInvoiceSchedules
repeatingInvoices
reportBalanceSheets
reportBankStatements
reportBudgetSummaries
reportProfitLosses
reportReports
reportTaxTypes
salesTaxBases
salesTaxPeriods
taxRateTaxComponents
taxRates
taxTypes
trackingCategories
trackingCategoryTrackingOptions
userRoles
users