README

有一个Discord社区。 https://discord.gg/VYau8hgwrm 如需快速帮助，请在适当的频道提问。

Laravel包，用于与Xero API交互

观看视频教程 https://www.youtube.com/watch?v=sORX2z-AH1k

Xero API文档可以在以下位置找到： https://developer.xero.com/documentation/

在您能够与Xero集成之前，您需要创建一个应用，前往 https://developer.xero.com/myapps 注册新的应用。

对于授权类型选择，Auth code (web app)

对于OAuth 2.0重定向URI，输入您要从应用程序连接到Xero的全URL，例如 https://domain.com/xero/connect

安装

您可以通过composer安装此包

composer require dcblogdev/laravel-xero

配置

您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="Dcblogdev\Xero\XeroServiceProvider" --tag="config"

静态加密令牌

您可以通过在.env文件中设置以下内容来启用静态令牌加密

XERO_ENCRYPT=true

这将使用Laravel原生加密库来确保令牌在静态状态下加密。

迁移

您可以使用以下命令发布迁移

php artisan vendor:publish --provider="Dcblogdev\Xero\XeroServiceProvider" --tag="migrations"

迁移发布后，您可以运行迁移来创建令牌表

php artisan migrate

.ENV配置 确保您已在.env文件中设置了以下内容

XERO_CLIENT_ID=
XERO_CLIENT_SECRET=
XERO_REDIRECT_URL=https://domain.com/xero/connect
XERO_LANDING_URL=https://domain.com/xero
XERO_WEBHOOK_KEY=

中间件

要限制只有认证用户才能访问路由，有一个名为XeroAuthenticated的中间件路由

将XeroAuthenticated添加到路由中，以确保用户已认证

Route::group(['middleware' => ['web', 'XeroAuthenticated'], function()

要访问令牌模型，请引用此ORM模型

use Dcblogdev\Xero\Models\XeroToken;

多租户

要设置租户，请调用setTenantId并传入您的tenant_id

一旦设置，所有调用都将使用设置的租户。

setTenantId($tenant_id)

命令

刷新令牌

当使用Xero作为后台进程时，需要更新令牌，要自动化此过程，请使用以下命令

php artisan xero:keep-alive

这将在令牌到期时刷新令牌。建议将其添加到计划中，例如在App\Console\Kernel.php中添加命令到计划中。

protected function schedule(Schedule $schedule)
{
    $schedule->command('xero:keep-alive')->everyFiveMinutes();
}

用法

路由示例

Route::group(['middleware' => ['web', 'auth']], function(){
    Route::get('xero', function(){

        if (! Xero::isConnected()) {
            return redirect('xero/connect');
        } else {
            //display your tenant name
            return Xero::getTenantName();
        }

    });

    Route::get('xero/connect', function(){
        return Xero::connect();
    });
});

或使用中间件路由，如果用户没有令牌，则自动重定向以进行认证

Route::group(['middleware' => ['web', 'XeroAuthenticated']], function(){
    Route::get('xero', function(){
        return Xero::getTenantName();
    });
});

Route::get('xero/connect', function(){
    return Xero::connect();
});

一旦认证，您可以使用以下动词调用Xero::

Xero::get($endpoint, $array = [])
Xero::post($endpoint, $array = [])
Xero::put($endpoint, $array = [])
Xero::patch($endpoint, $array = [])
Xero::delete($endpoint, $array = [])

数组的第二个参数不一定需要，其需求取决于被调用的端点，请参阅API文档以获取更多详细信息。

这需要传递API端点，提供的URL https://api.xero.com/api.xro/2.0/，只有此URL之后的端点应使用，例如

Xero::get('contacts')

是否连接

任何时候需要检查Xero是否已认证，都可以调用->isConnected方法。该方法返回一个布尔值。

要执行Xero未连接时的操作，可以这样做

if (! Xero::isConnected()) {
    return redirect('xero/connect');
}

断开连接

要断开Xero的连接，请调用->disconnect()方法。

断开连接将向Xero发送POST请求以撤销连接，此外，将删除存储的令牌。

Xero::disconnect();

通常情况下，只有在存在连接时才需要运行此操作，因此将其包裹在 ->isConnected() 检查中是有意义的。

if (Xero::isConnected()) {
    Xero::disconnect();
}

联系人

Xero 提供了一种简洁的方式来处理 Xero 联系人。

要处理联系人，首先调用 ->contacts() 方法，然后调用其他方法。

Xero::contacts()

列出联系人

要列出联系人，请调用 contacts()->get() 方法。

关于列出联系人的 Xero 文档 - https://developer.xero.com/documentation/api/contacts#GET

可选参数是 $page 和 $where。$page 默认为 1，表示返回第一页，对于额外的页面，输入更高的页码，直到没有更多页面返回。API 不提供计数来确定有多少页。

Xero::contacts()->get(int $page = 1, string $where = null)

$where 允许传递筛选选项，最常见的筛选器已优化以确保所有规模组织的性能。我们建议您将筛选限制以下优化参数。

按名称筛选

Xero::contacts()->get(1, 'Name="ABC limited"')

按电子邮件筛选

Xero::contacts()->get(1, 'EmailAddress="email@example.com"')

按账户编号筛选

Xero::contacts()->get(1, 'AccountNumber="ABC-100"')

查看联系人

要查看单个联系人，可以调用传递联系人 id 的 find 方法。

Xero::contacts()->find(string $contactId)

创建联系人

要创建联系人，请调用传递联系人数据数组的 store 方法。

有关数组内容规范的详细信息，请参阅 https://developer.xero.com/documentation/api/contacts#POST

Xero::contacts()->store($data)

更新联系人

要更新联系人，需要两个参数：联系人 Id 和要更新的数据数组。

有关可以更新的字段的详细信息，请参阅 https://developer.xero.com/documentation/api/contacts#POST

Xero::contacts()->update($contactId, $data);

发票

Xero 提供了一种简洁的方式来处理 Xero 发票。

要处理发票，首先调用 ->invoices() 方法，然后调用其他方法。

Xero::invoices()

列出发票

要列出发票，请调用 invoices()->get() 方法。

关于列出发票的 Xero 文档 - https://developer.xero.com/documentation/api/invoices#get

可选参数是 $page 和 $where。$page 默认为 1，表示返回第一页，对于额外的页面，输入更高的页码，直到没有更多页面返回。API 不提供计数来确定有多少页。

Xero::invoices()->get(int $page = 1, string $where = null)

$where 允许传递筛选选项，最常见的筛选器已优化以确保所有规模组织的性能。我们建议您将筛选限制以下优化参数。

按状态筛选

Xero::invoices()->get(1, 'Status="AUTHORISED"')

按联系人 ID 筛选

Xero::invoices()->get(1, 'Contact.ContactID=guid("96988e67-ecf9-466d-bfbf-0afa1725a649")')

按联系人编号筛选

Xero::invoices()->get(1, 'Contact.ContactNumber="ID001"')

按参考编号筛选

Xero::invoices()->get(1, 'Reference="INV-0001"')

按日期筛选

Xero::invoices()->get(1, 'Date=DateTime(2020, 01, 01)')

按类型筛选

Xero::invoices()->get(1, 'Type="ACCREC"')

查看发票

要查看单个发票，可以调用传递发票 ID 的 find 方法。

Xero::invoices()->find(string $invoiceId)

在线发票

对于状态为已提交、已授权或已付款的发票，可以通过调用 onlineUrl 并传递 invoiceId 来查看在线发票。

Xero::invoices()->onlineUrl($invoiceId)

创建发票

要创建发票，请调用传递发票数据数组的 store 方法。

有关数组内容规范的详细信息，请参阅 https://developer.xero.com/documentation/api/invoices#post

Xero::invoices()->store($data)

更新发票

要更新发票，需要两个参数：发票 Id 和要更新的数据数组。

有关可以更新的字段的详细信息，请参阅 https://developer.xero.com/documentation/api/invoices#post

Xero::invoices()->update($invoiceId, $data);

PDF 资源

某些 Xero 资源支持以 PDF 格式下载。为此，您可以

$pdfInvoice = Xero::get("invoices/{$invoiceId}", null, true, 'application/pdf');
$pdfInvoice['body']; // will be the pdf as a pdf string for you to write out to storage etc.

变更日志

请参阅 变更日志 了解最近更改的详细信息。

贡献

欢迎贡献，并将得到充分认可。

贡献可以通过 Github 上的拉取请求接受。

拉取请求

• 记录任何行为更改 - 确保保持 readme.md 和任何其他相关文档的最新状态。

• 考虑我们的发布周期 - 我们试图遵循 SemVer v2.0.0。随机破坏公共 API 不是可选项。

• 每个特性一个拉取请求 - 如果你想做多件事，请发送多个拉取请求。

安全

如果你发现任何与安全相关的问题，请发送电子邮件到 dave@dcblog.dev，而不是使用问题跟踪器。

许可证

许可证。有关更多信息，请参阅许可证文件。