README

这是一个Xero API的客户库，包括OAuth界面和类似ORM的抽象。

这个库基于XeroAPI/XeroOAuth-PHP的功能流程，但更逻辑地分为面向对象的设计。

此库已与私有、公共和合作伙伴应用程序进行了测试。

要求

• PHP 5.5+
• php_curl 扩展 - 确保是最新版本（7.30+）
• php_openssl 扩展

设置

使用composer

composer require calcinai/xero-php

否则，只需下载该软件包并将其添加到自动加载器中。命名空间符合PSR-4规范。

用法

以下所有示例均针对XeroPHP\Models\Accounting命名空间中的模型。此外，还有PayrollAU、PayrollUS、Files和Assets的模型。

创建XeroPHP实例（包含示例配置）

$xero = new \XeroPHP\Application\PrivateApplication($config);

加载对象集合并遍历它们

$contacts = $xero->load(Contact::class)->execute();

foreach ($contacts as $contact) {
    print_r($contact);
}

加载单个页面的对象集合并遍历它们 （为什么？）

$contacts = $xero->load(Contact::class)->page(1)->execute();

foreach ($contacts as $contact) {
    print_r($contact);
}

搜索满足特定标准的对象

$xero->load(Invoice::class)
    ->where('Status', Invoice::INVOICE_STATUS_AUTHORISED)
    ->where('Type', Invoice::INVOICE_TYPE_ACCREC)
    ->execute();

通过GUID加载对象

$contact = $xero->loadByGUID(Contact::class, $guid);

或者创建并填充它

$contact = new Contact($xero);

$contact->setName('Test Contact')
    ->setFirstName('Test')
    ->setLastName('Contact')
    ->setEmailAddress('test@example.com');

保存它

$contact->save();

如果您创建了多个相同类型的对象，您可以通过将数组传递给$xero->saveAll()来批量保存它们。

从v1.2.0+开始，Xero上下文可以直接在创建对象时注入，这将暴露->save()方法。这对于对象保持与其关系的状态是必要的。

保存相关模型

如果您同时保存多个模型，默认情况下不会更新额外的模型属性。这意味着如果您正在保存带有新联系人的发票，则不会更新联系人的ContactID。如果您想更新相关模型的属性，可以将布尔标志true传递给保存方法。

$xero->save($invoice, true);

嵌套对象

$invoice = $xero->loadByGUID(Invoice::class, '[GUID]');
$invoice->setContact($contact);

附件

$attachments = $invoice->getAttachments();
foreach ($attachment as $attachment) {
    //Do something with them
    file_put_contents($attachment->getFileName(), $attachment->getContent());
}

//You can also upload attachemnts
$attachment = Attachment::createFromLocalFile('/path/to/image.jpg');
$invoice->addAttachment($attachment);

要设置附件的IncludeOnline标志，将true作为第二个参数传递给->addAttachment()。

PDF - 支持PDF导出的模型将继承一个->getPDF()方法，它返回PDF的原始内容。目前这仅限于发票和贷项通知。

有关更复杂的使用和嵌套/相关对象的示例，请参阅示例。还有一个使用此库的PHP示例应用程序。

Webhooks

如果您正在接收Xero的Webhooks，有一个Webhook类可以帮助处理请求和解析相关事件列表。

$webhook = new Webhook($application, $request->getContent());

/**
 * @return int
 */
$webhook->getFirstEventSequence();

/**
 * @return int
 */
$webhook->getLastEventSequence();

/**
 * @return \XeroPHP\Webhook\Event[]
 */
$webhook->getEvents();

见：Webhooks文档

验证Webhooks

为了确保Webhooks来自Xero，您应该验证Xero提供的传入请求头。

if (! $webhook->validate($request->headers->get('x-xero-signature'))) {
    throw new Exception('This request did not come from Xero');
}

见：签名文档

处理错误

您对Xero的请求可能会引起错误，您可能需要处理这些错误。您可能会遇到以下错误：

• HTTP 400 错误请求，通过发送无效数据，如格式错误的电子邮件地址。
• HTTP 503 请求频率超过限制，在短时间内快速调用API。
• HTTP 400 错误请求，请求的资源不存在。

这只是几个例子，您应该阅读官方文档以了解更多可能的错误。

抛出的异常

此库将解析Xero返回的响应，并在遇到这些错误之一时抛出异常。以下是一个表格，显示响应代码和抛出的相应异常

见：响应代码和错误文档

处理异常

要捕获和处理这些异常，您可以在请求周围包裹try / catch块，并根据需要处理每个异常。

try {
    $xero->save($invoice);
} catch (NotFoundException $exception) {
    // handle not found error
} catch (RateLimitExceededException $exception) {
    // handle rate limit error
}

见：与异常一起工作